Concepts

The hierarchy

Your company  (your API key — internally called a "Partner")
└── Account  (X-Account-Id header)
    └── Organization  (orgSlug in URL)
        ├── Workspaces  (workspace slug)
        └── Documents   (org-prefixed docpaths)

Every API call carries enough context to resolve a path through this tree:

Slugs come in two formats

This is the single most common source of 400 and 404 errors. Slugs are encoded two different ways depending on where they appear:

Hex-encoded slugs

Used in URL path parameters:

• /v1/org/{orgSlug} — {orgSlug} is hex-encoded
• /v1/workspace/{slug} — {slug} is hex-encoded
• /v1/org/{orgSlug}/document/... — {orgSlug} is hex-encoded

You get hex-encoded slugs from the slug field on:

• GET /v1/orgs
• GET /v1/org/{orgSlug}/workspaces

Original (raw) slugs

Used in:

• URL query parameters
• JSON request bodies
• Multipart form fields (e.g. addToWorkspaces)
• The leading segment of org-prefixed docpaths

You get original slugs from the originalSlug field on the same responses above.

Docpaths

A docpath identifies a document within an organization’s storage. It always has the shape:

{originalOrgSlug}/{folder}/{filename}.json

Example:

acme/custom-documents/contract.pdf-fc4beeeb-e436-454d-8bb4-e5b8979cb48f.json

Docpaths appear in:

• adds / deletes arrays on POST /v1/workspace/{slug}/update-embeddings
• from / to on POST /v1/org/{orgSlug}/document/move-files
• files array on DELETE /v1/org/{orgSlug}/document/remove-files

Two important rules:

1. The leading segment is the original org slug — not the hex-encoded one in the URL.
2. The docpath’s org must match the org in the URL. Cross-org operations are rejected with 400.

Default folder

If you don’t specify a folder when uploading, the document lands in custom-documents/ under the org. That folder cannot be deleted — it’s the catch-all for unfiled docs.

Workspaces and embedding

Uploading a document does not automatically make it queryable. To use a document in a workspace, either:

• Pass addToWorkspaces (comma-separated original slugs) at upload time, or
• Call POST /v1/workspace/{slug}/update-embeddings later with the docpath in adds.

Both paths require the workspace and document to belong to the same organization.