Create Resource

Method: POST /{api_prefix}/{collection_path}/ Auth: Flux API Key — always required for writes, even on public APIs. The key's role must grant create on this API, and the target collection's connection must allow create (off by default).

Creates a resource with its first revision and publishes it immediately — the same pipeline as a Management API write: schema validation, a new revision, vectorization. This is the REST twin of the MCP create_record tool and shares its semantics exactly.

URL Pattern

POST https://{environment_key}.fxns.io/{api_prefix}/{collection_path}/

Nested collections use the path to carry their parents — the REST equivalent of the MCP parents argument:

POST https://7c9h4pwu.fxns.io/assistant/users/usr_8f2k1/memories/

Request Body

Name
data
Type
object
Required
required
Description
The document body. Must match the collection schema — invalid documents return 422 with the standard content validation payload (errors[] with json_path).
Name
key
Type
string
Description
Optional external identifier for deduplication. Creating a second resource with the same key in the collection returns 409 external_id_conflict instead of a duplicate.

No other top-level fields are accepted (422 otherwise). There is no draft mode: the caller cannot opt out of publishing or validation.

POST does not accept an If-Match header: a precondition names the revision that must still be current, and a record being created has none. Conditional writes apply to PUT.

Response

201 Created:

{
  "resource_key": "kDLT9jjrcAzh",
  "revision_key": "r_2xW9",
  "write_units": 1,
  "published": true
}

write_units reports the weighted write charged for this call — max(1, ceil(embedded_tokens / 500)).

Example

curl -sS -X POST "https://7c9h4pwu.fxns.io/assistant/users/usr_8f2k1/memories/" \
  -H "Authorization: Simple <public_key>:<private_key>" \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "content": "Prefers concise answers with code examples; time zone is CET.",
          "kind": "preference",
          "source": "chat-2026-07-22"
        },
        "key": "pref-communication"
      }'

Errors

Status	`error_code`	When
401	—	Missing/invalid credentials. Writes never accept anonymous callers, including on public APIs.
403	`access_denied`	The key's role lacks the `create` grant on this API.
403	`collection_not_writable`	The collection's connection does not allow `create`. The body lists which collections do.
404	—	Unknown collection path, or a nested parent that doesn't exist / isn't owned by the chain (strict reference).
405	—	`PATCH`/`DELETE` are not supported on the Flux API. Updates are full replaces via `PUT`.
409	`external_id_conflict`	A resource with the supplied `key` already exists in this collection.
422	`content_validation_failed`	`data` failed schema validation — body carries `errors[]` with `json_path`, capped at 100.
402	`spend_cap_reached` / `plan_exhausted`	Billing block; machine-readable body.
502	`upstream_error`	The write pipeline failed or timed out. The outcome is unknown — verify with a GET before retrying; the API never retries writes automatically.

Failed calls are never billed.