POST/v1/assistants

Assistants

Long-lived agents that carry a model, instructions, and a set of tools, reused across many Threads and Runs. Wire-compatible with the OpenAI Assistants shim. An assistant is just the reusable config; you run it by creating a Thread and a Run against it.

Request

HTTP: POST
URL: /v1/assistants
Auth: api_key

Try it

curl https://api.fightclub.pro/v1/assistants \
  -H "Authorization: Bearer $FC_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Code Reviewer",
    "model": "fc:openai/gpt-4o-mini",
    "instructions": "Review pull requests for bugs and style.",
    "tools": [{"type":"file_search"}],
    "tool_resources": {"file_search": {"vector_store_ids": ["vs_abc"]}}
  }'
# => { "id":"asst_...", "object":"assistant", "model":"fc:openai/gpt-4o-mini", ... }

Example response

{
  "id": "asst_4Tn7",
  "object": "assistant",
  "created_at": 1782300000,
  "name": "handbook-bot",
  "model": "fc:openai/gpt-4o-mini",
  "instructions": "Answer only from retrieved files. Cite them.",
  "tools": [ { "type": "file_search" } ],
  "tool_resources": {},
  "metadata": {}
}

A representative 200 body. Ids and timestamps are illustrative.

Body parameters

Name	Type	Default	Description
model*	string	—	Model ref for the assistant (fc:/match:/slot:), e.g. fc:openai/gpt-4o-mini.
name	string	optional	Display name. Must be unique within your account (reusing one returns 409 assistant_name_in_use).
description	string	optional	Free-form description shown in the dashboard.
instructions	string	optional	System prompt applied to every run of this assistant.
tools	array	optional	Tools the assistant may use: { type:"file_search" } for managed RAG, or { type:"function", function:{ name, description, parameters } } for your own tools.
tool_resources	object	optional	Default resources for the tools, e.g. { file_search: { vector_store_ids: ["vs_..."] } } to attach stores at the assistant level.
temperature	number	optional	Default sampling temperature for runs, 0-2.
top_p	number	optional	Default nucleus sampling for runs, 0-1.
response_format	string \| object	auto	auto, or { type:"json_schema", json_schema:{...} } to force structured output on every run.
metadata	object	optional	Free-form map: up to 16 keys, keys <=64 chars, values <=512 chars.

* required.

Query parameters

Name	Type	Default	Description
limit	integer	20	Page size on GET /v1/assistants (1-100).
order	string	desc	asc \| desc by created_at.
after	string	optional	Cursor: id to start after.
before	string	optional	Cursor: id to end before.

Headers

Header	Dir	Description
idempotency-key	req →	De-dupe a create retry so you do not get two assistants.

Response fields

Name	Type	Description
id	string	Assistant id (asst_*).
object	string	"assistant".
created_at	integer	Unix timestamp.
name	string \| null	Name, or null.
description	string \| null	Description, or null.
model	string	The model ref you set.
instructions	string \| null	Instructions, or null.
tools	array	The tools you configured.
tool_resources	object	Attached resources (e.g. vector_store_ids).
temperature	number \| null	Default temperature, or null.
top_p	number \| null	Default top_p, or null.
response_format	string \| object	auto or the json_schema you set.
metadata	object	Your metadata.

Errors

401missing_tokenNo Authorization header was sent.
401invalid_auth_schemeThe scheme was neither Bearer nor Client.
401invalid_token_formatA Bearer token not prefixed ko_.
401invalid_tokenThe API key is unknown, revoked or expired.
403insufficient_scopeThe key is valid but lacks the required scope.
400invalid_modelmodel is missing or not a valid ref.
400invalid_tool_shapetools is not an array of valid tool objects, or a function tool's parameters schema is malformed.
400tool_not_supportedThe tool type is not supported on assistants.
400invalid_temperaturetemperature outside 0-2.
400invalid_top_ptop_p outside 0-1.
400invalid_namename is not a valid string.
400invalid_metadatametadata exceeds the key/length limits.
409assistant_name_in_useYou already have an assistant with this name.
404not_foundNo such assistant (also cross-tenant).

See the full error reference.

Related routes

GET	/v1/assistants	List assistants (query: limit, order, after, before).
GET	/v1/assistants/{id}	Retrieve one assistant.
POST	/v1/assistants/{id}	Modify an assistant (same body fields as create).
PATCH	/v1/assistants/{id}	Alias for modify.
DELETE	/v1/assistants/{id}	Delete an assistant; returns { id, object:"assistant.deleted", deleted:true }.

Notes

·An assistant holds no conversation state. State lives in Threads; you execute the assistant by POSTing a Run to a thread.
·Attach a vector store via tool_resources.file_search.vector_store_ids to give the assistant managed RAG over your documents.
·name is unique per developer; catch 409 assistant_name_in_use and reuse the existing assistant if you create idempotently.

Examples

assistants-with-tools →