Documents

Upload, confirm, sync, crawl, and remove the documents a project answers from. Ingestion is a multi-step flow, not a single POST.

dev · https://api.dev.oprag.ai

All 16 endpoints on this page require a Cognito JWT from a signed-in dashboard session. An integration key returns 401 on every one of them — see what an API key can reach.

POST /v1/projects/{projectId}/documents/upload-url

Presigned upload URL (single file). Response is client-sanitized — no S3 keys or bucket names.

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
filename string Required Original file name. Its extension decides the parser.
contentType string Optional MIME type of the file, e.g. application/pdf.

Request

JSON 
{
  "filename": "refund-policy.pdf",
  "contentType": "application/pdf"
}

Response

200 Success

JSON 
{
  "documentId": "doc_abc123",
  "filename": "refund-policy.pdf",
  "uploadUrl": "https://...",
  "metadataUploadUrl": "https://...",
  "metadataBody": "{\"metadataAttributes\":{\"tenant_id\":\"...\",\"project_id\":\"...\"}}",
  "expiresInSeconds": 900,
  "instructions": "1) PUT file to uploadUrl. 2) PUT metadataBody to metadataUploadUrl. 3) POST confirm. 4) POST sync."
}

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/projects/{projectId}/documents/upload-url' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{"filename": "refund-policy.pdf","contentType": "application/pdf"}'
POST /v1/projects/{projectId}/documents/bulk-upload-url

Presigned upload URLs (batch)

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
files object[] Optional One entry per file: filename and contentType.

Response

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/projects/{projectId}/documents/bulk-upload-url' \
  -H 'Authorization: Bearer <Cognito JWT>'
POST /v1/projects/{projectId}/documents/{documentId}/confirm

Confirm S3 upload

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.
documentId string Required Document within the project.

Query parameters

None.Acts on the resource named in the path; there is nothing to choose.

Body parameters

None.Confirms the upload identified by the path; everything needed is already on the job.

Response

Status codes

Status Meaning
202 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/projects/{projectId}/documents/{documentId}/confirm' \
  -H 'Authorization: Bearer <Cognito JWT>'
POST /v1/projects/{projectId}/documents/{documentId}/replace-url

Replace document (versioned)

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.
documentId string Required Document within the project.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
filename string Optional New file name. Defaults to the existing document's.
contentType string Optional MIME type of the file, e.g. application/pdf.

Response

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/projects/{projectId}/documents/{documentId}/replace-url' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/projects/{projectId}/documents/{documentId}/versions

List document version history

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.
documentId string Required Document within the project.

Query parameters

None.Neither paginated nor filtered from the query string.

Body parameters

None.GET requests carry no body.

Response

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/projects/{projectId}/documents/{documentId}/versions' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/projects/{projectId}/documents/{documentId}/preview-url

Presigned preview URL (5 min TTL, works without RAG)

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.
documentId string Required Document within the project.

Query parameters

None.Reads the resource named in the path; there is nothing else to select.

Body parameters

None.GET requests carry no body.

Response

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/projects/{projectId}/documents/{documentId}/preview-url' \
  -H 'Authorization: Bearer <Cognito JWT>'
GET /v1/projects/{projectId}/documents

List documents. Each item is DocumentApiResponse — client-safe fields only (no S3 keys or tenant internals).

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

Name Type Required Default Description
limit number Optional 50 Documents per page. Values above 100 are clamped to 100; a non-numeric or non-positive value falls back to 50.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "documents": [
    {
      "documentId": "doc_123",
      "projectId": "proj_abc123",
      "filename": "refund-policy.pdf",
      "status": "indexed",
      "contentType": "application/pdf",
      "sizeBytes": 245760,
      "uploadedAt": "2026-06-28T12:00:00.000Z",
      "updatedAt": "2026-06-28T12:05:00.000Z",
      "sourceType": "upload"
    }
  ]
}

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/projects/{projectId}/documents' \
  -H 'Authorization: Bearer <Cognito JWT>'
DELETE /v1/projects/{projectId}/documents/{documentId}

Delete document (S3 + KB)

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.
documentId string Required Document within the project.

Query parameters

None.Acts on the resource named in the path; there is nothing to choose.

Body parameters

None.DELETE requests carry no body.

Response

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X DELETE 'https://api.dev.oprag.ai/v1/projects/{projectId}/documents/{documentId}' \
  -H 'Authorization: Bearer <Cognito JWT>'
POST /v1/projects/{projectId}/documents/sync

Ingest uploaded documents (202 Accepted)

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Acts on the resource named in the path; there is nothing to choose.

Body parameters

None.Starts ingestion for the project's pending documents.

Response

200 Success

JSON 
{
  "documentCount": 2,
  "statuses": ["STARTING"],
  "companyId": "co_abc123",
  "projectId": "proj_abc123",
  "message": "Project-scoped ingestion started. Wait 1–5 minutes before chatting."
}

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/projects/{projectId}/documents/sync' \
  -H 'Authorization: Bearer <Cognito JWT>'
POST /v1/projects/{projectId}/documents/crawl

Crawl a public website (same domain, BFS) and create markdown documents per page. autoSync defaults to false.

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
url string Required Page to start crawling from. Must be HTTP or HTTPS.
maxPages number Optional Upper bound on pages fetched in this crawl.
autoSync boolean Optional Re-crawl on a schedule rather than once.
syncIntervalHours number Optional Hours between automatic re-crawls when autoSync is set.

Request

JSON 
{
  "url": "https://docs.example.com",
  "maxPages": 50,
  "autoSync": false,
  "syncIntervalHours": 24
}

Response

200 Success

JSON 
{
  "projectId": "proj_abc",
  "companyId": "co_xyz",
  "seedUrl": "https://docs.example.com",
  "pagesDiscovered": 12,
  "documents": [
    {
      "documentId": "doc_123",
      "filename": "docs.example.com-index.md",
      "status": "uploaded",
      "sourceType": "crawl",
      "sourceUrl": "https://docs.example.com/"
    }
  ],
  "crawlSourceId": "crawl_456",
  "message": "Crawled 12 pages from docs.example.com."
}

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/projects/{projectId}/documents/crawl' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://docs.example.com","maxPages": 50,"autoSync": false,"syncIntervalHours": 24}'
GET /v1/projects/{projectId}/documents/crawl-sources

List scheduled website crawl sources

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Neither paginated nor filtered from the query string.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "crawlSources": [
    {
      "crawlSourceId": "crawl_456",
      "seedUrl": "https://docs.example.com",
      "maxPages": 50,
      "syncIntervalHours": 24,
      "enabled": true,
      "lastCrawledAt": "2026-06-27T12:00:00.000Z",
      "nextCrawlAt": "2026-06-28T12:00:00.000Z",
      "lastPageCount": 12,
      "createdAt": "2026-06-27T12:00:00.000Z",
      "updatedAt": "2026-06-27T12:00:00.000Z"
    }
  ]
}

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/projects/{projectId}/documents/crawl-sources' \
  -H 'Authorization: Bearer <Cognito JWT>'
DELETE /v1/projects/{projectId}/documents/crawl-sources/{crawlSourceId}

Disable a scheduled crawl source (does not delete crawled documents)

Auth Cognito JWT member

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.
crawlSourceId string Required Crawl source attached to the project.

Query parameters

None.Acts on the resource named in the path; there is nothing to choose.

Body parameters

None.DELETE requests carry no body.

Response

200 Success

JSON 
{
  "crawlSourceId": "crawl_456",
  "enabled": false
}

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X DELETE 'https://api.dev.oprag.ai/v1/projects/{projectId}/documents/crawl-sources/{crawlSourceId}' \
  -H 'Authorization: Bearer <Cognito JWT>'
POST /v1/projects/{projectId}/connector-sources

Attach a connector source to a project and run initial inline sync (max 50 documents). Documents are uploaded; call documents/sync to ingest.

Auth Cognito JWT admin

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Everything it needs is in the request body.

Body parameters

Name Type Required Description
connectionId string Required An existing connector connection in this workspace.
provider "notion" | "gdrive" | "github" Required Which provider the connection belongs to.
config any Optional Provider-specific selection, e.g. which Notion database or Drive folder.

Request

JSON 
{
  "connectionId": "conn_abc123",
  "provider": "github",
  "config": { "owner": "acme", "repo": "docs", "path": "guides" }
}

Response

200 Success

JSON 
{
  "connectorSource": {
    "connectorSourceId": "csrc_xyz",
    "projectId": "proj_abc",
    "connectionId": "conn_abc123",
    "provider": "github",
    "config": { "owner": "acme", "repo": "docs", "path": "guides" },
    "status": "idle",
    "documentCount": 3,
    "lastSyncAt": "2026-06-28T12:10:00.000Z",
    "createdAt": "2026-06-28T12:10:00.000Z",
    "updatedAt": "2026-06-28T12:10:00.000Z"
  },
  "documentCount": 3,
  "message": "Synced 3 documents from github. Run Sync documents to index."
}

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/projects/{projectId}/connector-sources' \
  -H 'Authorization: Bearer <Cognito JWT>' \
  -H 'Content-Type: application/json' \
  -d '{"connectionId": "conn_abc123","provider": "github","config": { "owner": "acme", "repo": "docs", "path": "guides" }}'
GET /v1/projects/{projectId}/connector-sources

List connector sources configured for a project

Auth Cognito JWT admin

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.

Query parameters

None.Neither paginated nor filtered from the query string.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "connectorSources": [
    {
      "connectorSourceId": "csrc_xyz",
      "projectId": "proj_abc",
      "connectionId": "conn_abc123",
      "provider": "github",
      "config": { "owner": "acme", "repo": "docs", "path": "" },
      "status": "idle",
      "documentCount": 3,
      "createdAt": "2026-06-28T12:10:00.000Z",
      "updatedAt": "2026-06-28T12:10:00.000Z"
    }
  ]
}

Status codes

Status Meaning
200 Success.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/projects/{projectId}/connector-sources' \
  -H 'Authorization: Bearer <Cognito JWT>'
POST /v1/projects/{projectId}/connector-sources/{connectorSourceId}/sync

Re-sync documents from the external connector (max 50 per run)

Auth Cognito JWT admin

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.
connectorSourceId string Required Connector source attached to the project.

Query parameters

None.Acts on the resource named in the path; there is nothing to choose.

Body parameters

None.Re-syncs the connector source identified by the path.

Response

200 Success

JSON 
{
  "connectorSource": {
    "connectorSourceId": "csrc_xyz",
    "status": "idle",
    "documentCount": 4,
    "lastSyncAt": "2026-06-28T13:00:00.000Z"
  },
  "documentCount": 4,
  "message": "Synced 4 documents. Run Sync documents to index."
}

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/projects/{projectId}/connector-sources/{connectorSourceId}/sync' \
  -H 'Authorization: Bearer <Cognito JWT>'
DELETE /v1/projects/{projectId}/connector-sources/{connectorSourceId}

Remove the connector source record. Previously synced project documents are not deleted in this MVP.

Auth Cognito JWT admin

Path parameters

Name Type Required Description
projectId string Required Project the request applies to. Must belong to the calling workspace.
connectorSourceId string Required Connector source attached to the project.

Query parameters

None.Acts on the resource named in the path; there is nothing to choose.

Body parameters

None.DELETE requests carry no body.

Response

200 Success

JSON 
{
  "connectorSourceId": "csrc_xyz",
  "deleted": true,
  "message": "Connector source removed. Previously synced documents were not deleted."
}

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
401 Missing or expired JWT.
403 The signed-in user's role does not allow this.
404 No such resource in this workspace.
429 Rate limited. See rate limits.

curl

Shell 
curl -X DELETE 'https://api.dev.oprag.ai/v1/projects/{projectId}/connector-sources/{connectorSourceId}' \
  -H 'Authorization: Bearer <Cognito JWT>'

Ready to ship?

Get started free