Core concepts | DJC AI API

Workspaces and identity

Everything in the app belongs to a workspace — the organisation you switch between in the top-left of the app. A token is createdwhile you are in a workspace and is bound to it: it acts as you, in that workspace. It sees every knowledge base there and the flows you own there, and it cannot reach any other workspace. Need to automate two workspaces? Create a token in each.

/me returns the orgId (workspace) and userId the token acts as. They are informational — you never send them.

Credits

Calls that run a model spend credits from your balance in that workspace, at the same rate as the app:

Call	What it spends
`POST …/ask`	One small model answer plus an embedding of the question.
`POST …/submissions`	Extraction over the material (≈ input tokens + ⅓ output) plus embeddings for every pair. Web search, when enabled, adds a per-search fee.
`POST …/entries`, `…/import`, edits that change text	Embeddings only — tiny.
`…/nodes/{id}/test`, `…/execute`	Whatever the LLM nodes in that flow use, per item. Test runs bill too.
`POST …/search`, every `GET`	Nothing.

When the balance reaches zero the call answers 402 INSUFFICIENT_CREDITS with the balance in details.balance. Top up in the app; nothing is queued or retried on our side.

Agents and loops

Retrieval (search) is free — iterate with it, and reserve ask, extraction and flow runs for when the answer matters.

The ids you pass around

Id	Shape	Where it comes from
`kbId`	UUID	`GET /bases`, the app's knowledge-base settings, or the `POST /bases` response.
entry `id`	UUID	Any entries listing, search hit or create response.
`sourceId`, message `id`	UUID	Uploads and the submission history.
`flowId`	UUID	`GET /flows`, the flow's settings dialog, or `POST /flows`.
`nodeId`	`node1`, `node2`, …	Human-readable, stable, visible on the canvas. Auto-assigned when you omit `id`.
`edgeId`	`e-node1-node2`, `e-node4-true-node5`	Derived from its endpoints (and branch).
`executionId`	UUID	The `202` from `execute`.

An id that is not a UUID, or that belongs to another workspace, answers 404.

Request and response shapes

JSON in, JSON out, UTF-8. Send Content-Type: application/json on every body-carrying call except file uploads (multipart/form-data).
Timestamps are ISO 8601 in UTC.
Creates return 201; the asynchronous execute returns 202; everything else 200.
Errors always have the same body — see Errors.

Error shape

{ "success": false, "error": "Invalid body", "code": "BAD_REQUEST", "details": { "fieldErrors": { "answer": ["Required"] } } }

Working with AI agents

The API was designed to be driven by an agent (Claude, ChatGPT, your own). Give it the credentials JSON from the token page and a link to this site, and tell it what you want. Good habits to ask of it:

Start with /me, then inspect (GET /bases, GET …/entries, GET …/graph) before changing anything you did not ask about.
Search before adding an entry; prefer editing over duplicating.
Prefer surgical edits (PATCH a node with configPatch) over rebuilding a whole graph.
Report what it changed by id — entry ids and question text, node ids and labels.

A read-only token is the safe way to let an agent explore before you trust it with write access.

Questions? admin@djc.ai