Ingest external content

If no connector exists for a system, send its content through the ingestion API. Orcha indexes ingested documents for search_context with your own citations and provenance. These documents work 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"
  }
}

Make the idempotencyKey from the source system, object, and revision. Orcha then recognizes a replay. The content limit is 5 MB. The metadata limit is 16 KB. This endpoint requires the write permission.

Replay behavior

You can safely call the endpoint from sync jobs that retry:

• New work returns 202 Accepted.
• An identical replay returns 200 OK with deduplicated: true.
• If you use a key again with different content, the endpoint returns 409 Conflict. Use a new key. Usually, a new key comes from a new revision.

Poll for status

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

The status is pending, indexing, indexed, or failed. The response also has the content hash, indexing time, citation, and any available error. When the status is indexed, search_context returns the document with the citation that you supplied.