> ## Documentation Index > Fetch the complete documentation index at: https://docs.decimal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an agent > Create an agent by registering its baseline manifest. Returns 201 with the new agent's id, the baseline manifest it was created from, and how many of the requested skills were assigned. A skill that can't be attached — unknown id, seeded demo data, or the plan's linked-skill allowance used up — is reported in ``skills_failed`` rather than failing the whole create: the agent is the thing being made here, and losing it because one skill id was stale would be the wrong trade. ``skills_failed_detail`` carries the reason, and for a plan refusal an ``error_code`` the UI can key an upgrade prompt off. ``skill_ids`` may name your own skills OR public registry skills. Attaching a registry skill here is free on every plan (2026-08-22 pricing decision: the moment that demonstrates the product isn't paywalled) — the ``Pro+`` gate applies to curating an agent's skills afterwards, not to this. The quantity cap is unchanged either way. ## OpenAPI ````yaml /openapi.json post /api/v1/agents openapi: 3.1.0 info: title: DecimalAI Platform description: Agent Dataset Lifecycle Platform — Backend API version: 0.1.0 servers: - url: https://api.decimal.ai description: Production security: - BearerAuth: [] tags: - name: traces description: >- Ingest, search, and inspect agent execution traces. A trace is the atomic unit of the platform — every other feature (evaluation, compatibility scoring, dataset building) operates on traces. Each trace is auto-tagged with the manifest hash of the agent that produced it. - name: eval-scores description: >- Push, fetch, and aggregate per-trace evaluation scores. Scores carry source provenance (built-in, DeepEval, LangSmith, custom) and feed the unified decision engine, which produces a keep / repair / replay / drop verdict per trace. - name: skills description: >- Manage reusable instruction blocks (SKILL.md files) that modify agent behavior. Skills are first-class manifest components — changes to a skill appear in your regression-check impact reports. Use these endpoints to create, version, fork, and sync skills with your local SKILL.md files. - name: manifests description: >- Register and inspect manifest versions. A manifest is a snapshot of your agent's structural identity (tools, prompts, models, skills) at a point in time. The SDK registers manifests automatically; these endpoints expose the underlying records. - name: datasets description: >- Build versioned SFT/DPO training datasets from manifest-classified, eval-scored traces. Datasets are reproducible — each version locks the manifest and filter set used to build it. Export as JSONL, Parquet, or push to HuggingFace Hub. - name: replay description: >- Re-execute historical traces against a new manifest version. Replay is the deferred-future capability for behavioral verification of agent changes. The SDK creates a replay batch, your worker executes each task, then submits results back here for eval scoring. - name: registry description: >- Browse and install published skills from the public skills registry. Each registry skill carries a SkillScore — an evidence-tiered quality composite computed from real-world evals, benchmarks, and ratings across organizations. Installing creates a fork in your org — edits don't affect the public version. - name: agents description: >- List and inspect agents, plus their multi-agent topology (orchestrator → sub-agent edges discovered from traces). Agents are identified by a stable agent_name string set in your SDK init() call. - name: import description: >- Bulk-import historical traces from another observability platform or a JSONL backup. Useful for migrating from LangSmith / Braintrust / Langfuse. Duplicate trace IDs are silently skipped — re-running an import is safe. paths: /api/v1/agents: post: tags: - agents summary: Create an agent description: >- Create an agent by registering its baseline manifest. Returns 201 with the new agent's id, the baseline manifest it was created from, and how many of the requested skills were assigned. A skill that can't be attached — unknown id, seeded demo data, or the plan's linked-skill allowance used up — is reported in ``skills_failed`` rather than failing the whole create: the agent is the thing being made here, and losing it because one skill id was stale would be the wrong trade. ``skills_failed_detail`` carries the reason, and for a plan refusal an ``error_code`` the UI can key an upgrade prompt off. ``skill_ids`` may name your own skills OR public registry skills. Attaching a registry skill here is free on every plan (2026-08-22 pricing decision: the moment that demonstrates the product isn't paywalled) — the ``Pro+`` gate applies to curating an agent's skills afterwards, not to this. The quantity cap is unchanged either way. operationId: create_agent_api_v1_agents_post parameters: - name: Authorization in: header required: false schema: type: string title: Authorization - name: X-Workspace-Id in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Workspace-Id - name: decimal_session in: cookie required: false schema: anyOf: - type: string - type: 'null' title: Decimal Session requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentRequest' responses: '201': description: Successful Response content: application/json: schema: type: object additionalProperties: true title: Response Create Agent Api V1 Agents Post example: agent_name: travel-planner agent_id: 5f2c1a90-0f1e-4b6c-9a11-2b3c4d5e6f70 manifest_id: 9c8b7a60-1122-4c33-8d44-55e66f778899 version_label: v1 skills_assigned: 2 skills_failed: [] '400': description: Invalid agent_name. '409': description: An agent with this name already exists in this org. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: CreateAgentRequest: properties: agent_name: anyOf: - type: string - type: 'null' title: Agent Name description: >- Lowercase letters, digits, hyphens and underscores; 1–200 chars. Becomes the agent's URL path segment and must be unique per org. description: anyOf: - type: string - type: 'null' title: Description description: Free-text note about what this agent does. system_prompt: anyOf: - type: string - type: 'null' title: System Prompt description: >- The agent's system prompt. Stored as a `prompt` component on the baseline manifest, so later prompt edits show up as drift. skill_ids: items: type: string type: array title: Skill Ids description: >- Skills to attach to the new agent. Either one of your org's own skills, or any public registry skill — attaching registry skills while creating an agent is free on every plan (curating them afterwards is Pro+). Capped by the plan's linked-skill allowance; an id that is neither is reported in `skills_failed`. type: object title: CreateAgentRequest description: >- Body of ``POST /api/v1/agents``. ``agent_name`` is Optional[str] here despite being REQUIRED by the contract, and that is on purpose: declaring it `str` would make a missing field a FastAPI 422 while an empty-string field is a 400, so the caller would have to handle two error shapes for one mistake. Optional + an explicit check in the handler routes every name problem — absent, empty, wrong shape, reserved prefix — through the same 400 with the same message field. (A genuinely non-string value, e.g. `{"agent_name": 12}`, is still a 422; pydantic rejects it before the handler runs.) HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: BearerAuth: type: http scheme: bearer description: Enter your API key (e.g. dai_sk_test_key_001) ````