Skip to content

Use the REST API

The document API is plain HTTP and JSON. One envelope serves every read and write, and one filter grammar serves every list. This page teaches the shapes: create and update bodies, list filters, aggregates, entity tags (ETags), and errors. The machine-readable contract lives in the REST API reference.

For agents: Auth: Authorization: Bearer fct_… (static key) or Authorization: DPoP <token> plus a DPoP proof header (app token). Sequence: POST /Api/crm/Company with fields at the top level of the JSON body (201, envelope {data, meta}) → GET /Api/crm/Company/<id> (store the ETag) → re-send it as If-None-Match: "<etag>" for a 304 → GET /Api/crm/Company?items=50&filters[status__eq]=active&sort=-updated_at → PATCH (merge patch; null removes a key) → DELETE (204). Validation failures are 422 with {error, details:[{field, message, code, params?}]}. A hidden or missing document is 404; a deleted one is 410.

Use the raw API when:

  • You call Facet from a language without an SDK.
  • You need direct control over filters, paging, or cache validators.
  • You debug an integration and must see the raw shapes.

For TypeScript apps, prefer the TypeScript SDK: types, paging, typed errors.

  • A running Facet instance and a credential with a read grant on the target doctype. Creates and updates need write; delete needs delete.

  • Three credentials work on every route:

  • A write with a cookie session must carry X-Requested-With: XMLHttpRequest. A Bearer or DPoP request without a session cookie is exempt.

  • Paths carry a lowercase domain first: /Api/crm/Company. An uppercase first segment (/OAuth, /Ws) names an infrastructure route, never a domain.

    The examples use https://facet.example.com and the crm.Company doctype. Replace both with your values.

Terminal window
curl "https://facet.example.com/Api/crm/Company/01JD8W2G7Q5M2X9K4T6VBNR8D" \
-H "Authorization: Bearer $FACET_API_KEY"

The answer is one { data, meta } envelope. data holds the fields the doctype declares. meta holds system metadata and is never writable:

{
"data": { "name": "Acme", "status": "active" },
"meta": {
"id": "crm.Company.01JD8W2G7Q5M2X9K4T6VBNR8D",
"uri": "urn:facet:crm:Company:01JD8W2G7Q5M2X9K4T6VBNR8D",
"mid": "01JD8W2G7Q5M2X9K4T6VBNR8E",
"domain": "crm", "doc_type": "Company",
"version": 1, "schema_version": 1,
"display_name": "Acme",
"created_at": "2026-01-01T12:00:00Z", "updated_at": "2026-01-01T12:00:00Z"
}
}
Field Meaning
id, uri Document id in the dotted {domain}.{Doctype}.{id} form; canonical URN.
mid ULID of the last mutation applied to the document.
domain, doc_type The domain id and the doctype name.
version, schema_version The document version and the doctype schema version.
display_name Human label from the doctype template; null when the doctype declares none.
created_at, updated_at Timestamps in UTC.

Fields ride at the top level of the JSON body. There is no content wrapper:

Terminal window
curl -X POST "https://facet.example.com/Api/crm/Company" \
-H "Authorization: Bearer $FACET_API_KEY" -H "Content-Type: application/json" \
-d '{ "name": "Acme", "status": "active" }'

The answer is 201 with the envelope from step 1. A wrapped body names no doctype field, so it fails with 422:

{
"error": "Document validation failed",
"details": [{ "field": "content", "code": "unknown_field",
"message": "is not a defined field — this looks like a wrapped body: send the fields at the top level; there is no content wrapper" }]
}

To create a parent with its children in one call, send $content and $children. The call is one transaction: a child failure rolls the whole call back. The $children keys are relationship names on the doctype:

Terminal window
curl -X POST "https://facet.example.com/Api/crm/Company" \
-H "Authorization: Bearer $FACET_API_KEY" -H "Content-Type: application/json" \
-d '{ "$content": { "name": "Acme", "status": "active" },
"$children": { "memberships": [
{ "role": "primary", "contact": "crm.Contact.01JD9K2G7Q5M2X9K4T6VBNR8E" } ] } }'

The answer carries an extra children key, grouped by relationship name. Each entry carries the same { data, meta } shape as the parent:

{ "children": { "memberships": [
{ "data": { "role": "primary" }, "meta": { "id": "crm.CompanyMembership.01JD9K2G7Q5M2X9K4T6VBNR8F" } } ] } }

PATCH sends a JSON merge patch (RFC 7386). A null value removes a key from the document; the mutation log records the removal as an unset entry:

Terminal window
curl -X PATCH "https://facet.example.com/Api/crm/Company/01JD8W2G7Q5M2X9K4T6VBNR8D" \
-H "Authorization: Bearer $FACET_API_KEY" -H "Content-Type: application/json" \
-d '{ "status": "churned", "website": null }'

The answer is 200 with the updated envelope. Document routes are PATCH-only: a PUT answers 405 with an Allow header, because PUT is reserved for definition authoring on core.DocType.

DELETE soft-deletes the document and answers 204 with no body. The document becomes a tombstone; a restore call brings it back (see 410 under Errors).

Terminal window
curl "https://facet.example.com/Api/crm/Company?items=50&filters[status__eq]=active&sort=-updated_at" \
-H "Authorization: Bearer $FACET_API_KEY"

The collection envelope holds an array of { data, meta } rows. The list meta carries count and more:

{
"data": [
{ "data": { "name": "Acme", "status": "active" },
"meta": { "id": "crm.Company.01JD8W2G7Q5M2X9K4T6VBNR8D", "created_at": "2026-01-01T12:00:00Z", "updated_at": "2026-01-02T09:30:00Z" } },
{ "data": { "name": "Globex", "status": "active" },
"meta": { "id": "crm.Company.01JD9K2G7Q5M2X9K4T6VBNR8E", "created_at": "2026-01-03T08:00:00Z", "updated_at": "2026-01-03T15:11:42Z" } }
],
"meta": { "count": 2, "more": false }
}

Paging: page starts at 1; items clamps to 1..1000; the defaults are page 1, 100 items, sort id. count caps at 1000 and includes one probe row when a further page exists — a one-item page against a larger set reports count: 2. more is true when a further page exists.

Filter keys are field__operator pairs:

Operator Matches
__eq, __ne Equal, not equal.
__gt, __gte, __lt, __lte Comparison.
__match Contains the substring, case-insensitive.
__starts_with Starts with the value, case-insensitive.
__between Inclusive range; the value is a two-element array.
__in Membership; the value is an array of at most 100 entries.
__currency Money amount in one currency.
__contains, __overlaps, __within Range tests on period and dateperiod fields.
search (bare key, no suffix) Substring match on the document’s search corpus.

Every doctype also accepts the system targets id, created_at, updated_at, and deleted_at. Array values on the query string ride JSON-encoded: filters[value__between]=%5B%22USD%202500%22%2C%22USD%201000%22%5D. Sort entries take a - prefix for descending. Numeric types (integer, money, duration) sort numerically, not as text. Unknown filter fields answer 422 with unknown_filter_field; unknown parameters answer 422 Unknown parameter '<key>'. A typo never degrades to an unfiltered result.

aggregate=count counts the full filtered set. It ignores page and items and caps the count at 1000. It answers { "data": [], "meta": { "count": 87, "more": false } }:

Terminal window
curl "https://facet.example.com/Api/crm/Company?aggregate=count&filters[status__eq]=active" \
-H "Authorization: Bearer $FACET_API_KEY"

aggregate=sum|avg|min|max needs field=. The field must be a top-level integer, duration, or money field. A field aggregate runs over the full filtered set with no cap. A money field returns a bag with one entry per currency present, never a single cross-currency total; amounts are decimal strings:

Terminal window
curl "https://facet.example.com/Api/crm/Deal?aggregate=sum&field=value" \
-H "Authorization: Bearer $FACET_API_KEY"
{ "data": { "value": { "USD": "123456.78" } }, "meta": { "count": 87, "more": false } }

An empty set answers value: 0 for sum, value: null for avg, min, and max, and value: {} for a money field. meta.count counts matching rows; rows that omit the field still count.

Every read emits a strong ETag. On a single document the tag is the ULID of its last mutation. On a collection the tag combines the role, the request, and the doctype version. Send the tag back in If-None-Match, and the server answers 304 Not Modified when nothing changed:

GET /Api/crm/Company/01JD8W2G7Q5M2X9K4T6VBNR8D
→ 200
ETag: "01JD8W2G7Q5M2X9K4T6VBNR8E"
GET /Api/crm/Company/01JD8W2G7Q5M2X9K4T6VBNR8D
If-None-Match: "01JD8W2G7Q5M2X9K4T6VBNR8E"
→ 304

A 304 carries Cache-Control: no-cache, so the client revalidates on the next read. A write gives the document a new tag, so a stale client never receives a false 304.

The QUERY method (RFC 10008) carries list parameters in a JSON body only. New clients should prefer it; GET keeps the body plus query-string merge for backward compatibility, and the query string wins on a collision:

Terminal window
curl -X QUERY "https://facet.example.com/Api/crm/Company" \
-H "Authorization: Bearer $FACET_API_KEY" -H "Content-Type: application/json" \
-d '{ "items": 50, "filters": { "status__eq": "active" }, "sort": ["-updated_at"] }'

Any query-string parameter on a QUERY request answers 422. A body with a non-JSON Content-Type answers 415. An empty body means the defaults: page 1, 100 items, sort id. Responses carry Accept-Query: application/json, so a client can discover the format from any list response.

Status Meaning
422 Validation failed, or a filter, sort, select, or parameter name is wrong.
403 Class denial: the credential holds no permission on the doctype at all.
404 Non-disclosing: a missing document and a hidden one are indistinguishable.
405 Method not allowed; the Allow header names the accepted methods.
409 Concurrent write on the document. Re-issue the same request.
410 Tombstone: the document is deleted.
415 A non-JSON Content-Type on a body-consuming request.

A 422 body carries one entry per failed field. Each entry holds field, message, and code; a params map holds the interpolations behind a templated code when present (step 2 shows a full example). A concurrent write answers { "error": "Concurrent write on this document — retry the request" }. The losing write never landed, so a fresh write takes the next free slot.

A read of a tombstone answers 410 with the surviving label:

{ "error": "Document 01JD8W2G7Q5M2X9K4T6VBNR8D was deleted", "display_name": "Acme", "deleted_at": "2026-01-01T12:00:00Z" }

Restore the document with POST /Api/crm/Company/<id>/restore and an empty JSON body. Every error response sets Cache-Control: no-store, so no cache keeps a stale failure.

One sequence covers the full create, read, update, and delete (CRUD) cycle:

Terminal window
BASE="https://facet.example.com"
AUTH="Authorization: Bearer $FACET_API_KEY"
ID="01JD8W2G7Q5M2X9K4T6VBNR8D"
curl -s -X POST "$BASE/Api/crm/Company" -H "$AUTH" -H "Content-Type: application/json" \
-d '{ "name": "Initech", "status": "lead" }' # → 201: meta.id, fresh ETag
curl -s -D - -o /dev/null "$BASE/Api/crm/Company/$ID" -H "$AUTH" # → 200: copy the ETag
curl -s -D - -o /dev/null "$BASE/Api/crm/Company/$ID" -H "$AUTH" \
-H 'If-None-Match: "01JD8W2G7Q5M2X9K4T6VBNR8E"' # → 304 when unchanged
curl -s "$BASE/Api/crm/Company?filters[status__eq]=active&sort=-updated_at&items=10" -H "$AUTH" # → 200
curl -s -X PATCH "$BASE/Api/crm/Company/$ID" -H "$AUTH" -H "Content-Type: application/json" \
-d '{ "status": "active" }' # → 200: updated envelope
curl -s -X DELETE "$BASE/Api/crm/Company/$ID" -H "$AUTH" -o /dev/null -w '%{http_code}\n' # → 204

A document you just created answers 404.

Row scopes on the role, or a missing grant, hide the row. A 404 never discloses existence. Check what the credential may attempt — see Gate your UI with the manifest.

A list call answers 422 Unknown parameter or unknown_filter_field.

A typo sits in the parameter grammar. Check the key and the operator against the table in step 4.

A conditional read returns 200 every time.

The If-None-Match value must match the ETag verbatim, quotes included.

A write answers 409.

Two writers raced on one document. The losing write never landed. Re-issue the same request.

A create answers 422 with unknown_field on content.

The body is wrapped in a content key. Send the fields at the top level of the JSON body.