Ingest external content

When no connector exists for a system, push its content through the ingestion API. Ingested documents are indexed for search_context with your own citations and provenance, like documents from a connected source.

Submit a document

curl -X POST \
  -H "Authorization: Bearer orca_your_token" \
  -H "Content-Type: application/json" \
  -d @document.json \
  https://app.tryorcha.com/api/v1/ingest

{
  "idempotencyKey": "github:org/repo:docs/guide.md:abc123",
  "title": "Deployment Guide",
  "content": "# Deployment\n\nProduction requirements...",
  "mimeType": "text/markdown",
  "externalId": "docs/guide.md",
  "externalRevision": "abc123",
  "metadata": {
    "repository": "org/repo"
  },
  "citation": {
    "provider": "github",
    "objectId": "docs/guide.md",
    "deepLink": "https://github.com/org/repo/blob/abc123/docs/guide.md",
    "location": "docs/guide.md",
    "version": "abc123"
  }
}

Build the idempotencyKey from the source system, object, and revision so replays are recognized. Content is limited to 5 MB and metadata to 16 KB. Requires write permission.

Replay behavior

The endpoint is safe to call from sync jobs that retry:

• New work returns 202 Accepted.
• An identical replay returns 200 OK with deduplicated: true.
• Reusing a key with different content returns 409 Conflict; use a new key (typically a new revision) instead.

Poll for status

curl -H "Authorization: Bearer orca_your_token" \
  https://app.tryorcha.com/api/v1/ingest/document-id

Status is pending, indexing, indexed, or failed, with content hash, indexing time, citation, and any available error. Once indexed, the document is returned by search_context with the citation you supplied.