Documents API Reference

Learn about the document management endpoints and how to work with your ingested content.

Documents are the core content units in RAGaaS. Each document can have metadata that helps in organizing and filtering content.

POST/v1/documents

Fetch Documents

Fetch documents based on filters.

Authorization

Name
Authorization*
Type
string
Description
Bearer token authentication. Include your API key as Bearer your_api_key

Request Body

Name
namespaceId*
Type
string
Description
ID of the namespace containing the documents
Name
filterConfig*
Type
object
Description
Configuration for filtering documents
- Name
  documentIds*
  Type
  array<string>
  Description
  List of document IDs to filter
- Name
  documentExternalIds*
  Type
  array<string>
  Description
  List of external document IDs to filter
- Name
  documentTypes*
  Type
  array<enum<string>>
  Description
  List of document types to filter
  Available options: TEXT, URL, SITEMAP, WEBSITE
- Name
  metadata
  Type
  object(optional)
  Description
  Metadata filters to apply

Request

POST

/v1/documents

curl -X POST https://api.ragaas.dev/v1/documents \
  -H "Authorization: Bearer $RAGAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespaceId": "ns_123",
    "filterConfig": {
      "documentIds": ["doc_123", "doc_124"],
      "documentExternalIds": ["external_123"],
      "documentTypes": ["TEXT", "URL"],
      "metadata": {
        "category": "security",
        "status": "published"
      }
    }
  }'

Response Body

Name
success*
Type
boolean
Description
Indicates whether the request is successful or not. This is always true for success responses.
Name
message*
Type
string
Description
Human readable message mentioning the result of the request
Name
data*
Type
object
Description
Data returned from the API.
- Name
  documents*
  Type
  array<object>
  Description
  List of documents
  Name
  id*
  Type
  string
  Description
  Unique identifier of the document
  Name
  externalId*
  Type
  string
  Description
  External identifier of the document
  Name
  documentType*
  Type
  enum<string>
  Description
  Type of the document
  Available options: TEXT, URL, SITEMAP, WEBSITE
  Name
  metadata*
  Type
  object
  Description
  Metadata associated with the document
  Name
  createdAt*
  Type
  object
  Description
  Timestamp when the document was created
  Name
  isoString*
  Type
  string
  Description
  ISO 8601 formatted timestamp
  Name
  updatedAt*
  Type
  object
  Description
  Timestamp when the document was last updated
  Name
  isoString*
  Type
  string
  Description
  ISO 8601 formatted timestamp

Response

POST

/v1/documents

{
  "success": true,
  "message": "Documents retrieved successfully",
  "data": {
    "documents": [
      {
        "id": "doc_123",
        "externalId": "external_123",
        "documentType": "TEXT",
        "ingestionSource": "TEXT",
        "ingestionStatus": "SUCCESS",
        "ingestionError": null,
        "ingestJob": {
          "id": "job_123",      
        },
        "ingestJobRun": {
          "id": "job_run_123",          
        },
        "metadata": {
          "category": "security",
          "status": "published"
        },
        "createdAt": {
          "isoString": "2024-01-01T00:00:00Z"
        },
        "updatedAt": {
          "isoString": "2024-01-01T00:00:00Z"
        }
      }
    ]
  }
}

PATCH/v1/documents

Update Documents

Update documents based on filters.

Authorization

Name
Authorization*
Type
string
Description
Bearer token authentication. Include your API key as Bearer your_api_key

Request Body

Name
namespaceId*
Type
string
Description
ID of the namespace containing the documents
Name
filterConfig*
Type
object
Description
Configuration for filtering documents
- Name
  documentIds*
  Type
  array<string>
  Description
  List of document IDs to filter
- Name
  documentExternalIds*
  Type
  array<string>
  Description
  List of external document IDs to filter
- Name
  documentTypes*
  Type
  array<enum<string>>
  Description
  List of document types to filter
  Available options: TEXT, URL, SITEMAP, WEBSITE
- Name
  metadata
  Type
  object(optional)
  Description
  Metadata filters to apply
Name
data*
Type
object
Description
Data to update in the documents
- Name
  metadata*
  Type
  object
  Description
  Metadata to update in the documents

Request

PATCH

/v1/documents

curl -X PATCH https://api.ragaas.dev/v1/documents \
  -H "Authorization: Bearer $RAGAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespaceId": "ns_123",
    "filterConfig": {
      "documentIds": ["doc_123"],
      "documentExternalIds": [],
      "documentTypes": ["TEXT"],
      "metadata": {
        "category": "security"
      }
    },
    "data": {
      "metadata": {
        "status": "archived",
        "archivedAt": "2024-01-15T00:00:00Z"
      }
    }
  }'

Response Body

Name
success*
Type
boolean
Description
Indicates whether the request is successful or not. This is always true for success responses.
Name
message*
Type
string
Description
Human readable message mentioning the result of the request
Name
data*
Type
object
Description
Data returned from the API.
- Name
  documents*
  Type
  array<object>
  Description
  List of documents
  Name
  id*
  Type
  string
  Description
  Unique identifier of the document
  Name
  externalId*
  Type
  string
  Description
  External identifier of the document
  Name
  documentType*
  Type
  enum<string>
  Description
  Type of the document
  Available options: TEXT, URL, SITEMAP, WEBSITE
  Name
  metadata*
  Type
  object
  Description
  Metadata associated with the document
  Name
  createdAt*
  Type
  object
  Description
  Timestamp when the document was created
  Name
  isoString*
  Type
  string
  Description
  ISO 8601 formatted timestamp
  Name
  updatedAt*
  Type
  object
  Description
  Timestamp when the document was last updated
  Name
  isoString*
  Type
  string
  Description
  ISO 8601 formatted timestamp

Response

PATCH

/v1/documents

{
  "success": true,
  "message": "Documents updated successfully",
  "data": {
    "documents": [
      {
        "id": "doc_123",
        "externalId": "external_123",
        "documentType": "TEXT",
        "metadata": {
          "category": "security",
          "status": "archived",
          "archivedAt": "2024-01-15T00:00:00Z"
        },
        "createdAt": {
          "isoString": "2024-01-01T00:00:00Z"
        },
        "updatedAt": {
          "isoString": "2024-01-15T00:00:00Z"
        }
      }
    ]
  }
}

DELETE/v1/documents

Delete Documents

Delete documents based on filters.

Authorization

Name
Authorization*
Type
string
Description
Bearer token authentication. Include your API key as Bearer your_api_key

Request Body

Name
namespaceId*
Type
string
Description
ID of the namespace containing the documents
Name
filterConfig*
Type
object
Description
Configuration for filtering documents
- Name
  documentIds*
  Type
  array<string>
  Description
  List of document IDs to filter
- Name
  documentExternalIds*
  Type
  array<string>
  Description
  List of external document IDs to filter
- Name
  documentTypes*
  Type
  array<enum<string>>
  Description
  List of document types to filter
  Available options: TEXT, URL, SITEMAP, WEBSITE
- Name
  metadata
  Type
  object(optional)
  Description
  Metadata filters to apply

Request

DELETE

/v1/documents

curl -X DELETE https://api.ragaas.dev/v1/documents \
  -H "Authorization: Bearer $RAGAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespaceId": "ns_123",
    "filterConfig": {
      "documentIds": ["doc_123"],
      "documentExternalIds": [],
      "documentTypes": ["TEXT"],
      "metadata": {
        "status": "archived"
      }
    }
  }'

Response Body

Name
success*
Type
boolean
Description
Indicates whether the request is successful or not. This is always true for success responses.
Name
message*
Type
string
Description
Human readable message mentioning the result of the request
Name
data*
Type
null
Description
Data returned from the API.

Response

DELETE

/v1/documents

{
  "success": true,
  "message": "Documents deleted successfully",
  "data": null
}

Error Codes

Name
NAMESPACE_NOT_FOUND
Description
The specified namespace does not exist
Name
DOCUMENTS_NOT_FOUND
Description
No documents match the filter criteria
Name
INVALID_FILTER_CONFIG
Description
Invalid filter configuration provided
Name
UPDATE_DOCUMENTS_FAILED
Description
Internal error while updating documents
Name
DELETE_DOCUMENTS_FAILED
Description
Internal error while deleting documents

Filter Configuration

Name
Document IDs
Description
Filter by specific document IDs using documentIds
Name
External IDs
Description
Filter by external IDs using documentExternalIds
Name
Document Types
Description
Filter by document types using documentTypes
Name
Metadata
Description
Filter by metadata key-value pairs using metadata