API reference

Skills

Create, discover, execute, and manage reusable capabilities for your agents.

Create Skill

Create a new skill record. Fails with an error if a skill with the same name already exists (optionally scoped to project_id).

Authorizations

ApiToken

API key authentication

Type

API Key (header: x-api-token)

Request Body

application/json

Unique identifier for the skill

Optional — scopes the uniqueness check to a project

Responses

Skill created, or a status:false error (e.g. duplicate name) — this endpoint returns 200 even on failure, check the status field

Content-Type

application/json

Whether the operation succeeded

Request builder

POST/skill

Interactive

Playground

Authorization

ApiToken

Body

Code samples

Use the configured request in your preferred language.

Retrieve Skill by name (query param)

Alternate lookup form: GET /skill?name=. Equivalent to GET /skill/{name}.

Authorizations

ApiToken

API key authentication

Type

API Key (header: x-api-token)

Parameters

Query Parameters

name*

Type

string

Required

fields

Comma-separated field projection, e.g. _id,name,title

Type

string

Responses

Skill data, or status:false if not found

Content-Type

application/json

Whether the operation succeeded

Request builder

GET/skill

Interactive

Playground

Authorization

ApiToken

Variables

Key

Value

name*

fields

Code samples

Use the configured request in your preferred language.

Get Skill by ID

Retrieve a skill by its MongoDB _id.

Authorizations

ApiToken

API key authentication

Type

API Key (header: x-api-token)

Parameters

Path Parameters

item_id*

Type

string

Required

Query Parameters

fields

Comma-separated field projection

Type

string

Responses

Skill data, or status:false if not found

Content-Type

application/json

Whether the operation succeeded

Request builder

GET/skill/id/{item_id}

Interactive

Playground

Authorization

ApiToken

Variables

Key

Value

item_id*

fields

Code samples

Use the configured request in your preferred language.

Get Skill by name

Retrieve a skill by its unique name.

Authorizations

ApiToken

API key authentication

Type

API Key (header: x-api-token)

Parameters

Path Parameters

name*

Type

string

Required

Query Parameters

fields

Type

string

Responses

Skill data, or status:false if not found

Content-Type

application/json

Whether the operation succeeded

Request builder

GET/skill/{name}

Interactive

Playground

Authorization

ApiToken

Variables

Key

Value

name*

fields

Code samples

Use the configured request in your preferred language.

Update Skill

Update a skill's fields. updated timestamp is set automatically.

Authorizations

ApiToken

API key authentication

Type

API Key (header: x-api-token)

Parameters

Path Parameters

item_id*

Type

string

Required

Request Body

application/json

Any subset of skill fields to set

Responses

status:true with a confirmation message, or status:false if not found

Content-Type

application/json

Whether the operation succeeded

Request builder

PUT/skill/{item_id}

Interactive

Playground

Authorization

ApiToken

Variables

Key

Value

item_id*

Body

Code samples

Use the configured request in your preferred language.

Delete Skill

Delete a skill by its MongoDB _id.

Authorizations

ApiToken

API key authentication

Type

API Key (header: x-api-token)

Parameters

Path Parameters

item_id*

Type

string

Required

Responses

status:true with the deleted id, or status:false if not found

Content-Type

application/json

Whether the operation succeeded

Request builder

DELETE/skill/{item_id}

Interactive

Playground

Authorization

ApiToken

Variables

Key

Value

item_id*

Code samples

Use the configured request in your preferred language.

Search Skills

Paginated search over skills in the project.

Authorizations

ApiToken

API key authentication

Type

API Key (header: x-api-token)

Request Body

application/json

MongoDB-style filter, e.g. {"name": {"$regex": "sync", "$options": "i"}}

[field, direction] e.g. ["name", 1]

Default1

Default10

Responses

Paginated skill list

Content-Type

application/json

Whether the operation succeeded

Request builder

POST/skill/search

Interactive

Playground

Authorization

ApiToken

Body

Code samples

Use the configured request in your preferred language.

Execute Skill by ID

Execute a skill by its MongoDB _id. Always dispatched via a Celery task; pass agent-config.delay: false to block and wait up to 300s for the result instead of getting a scheduled task id back immediately.

Authorizations

ApiToken

API key authentication

Type

API Key (header: x-api-token)

Parameters

Path Parameters

item_id*

Type

string

Required

Request Body

application/json

Responses

Scheduled (default) returns a skill_run_id + task_id; delay:false returns the actual result with skill_run_id attached

Content-Type

application/json

Whether the operation succeeded

Request builder

POST/skill/executor/id/{item_id}

Interactive

Playground

Authorization

ApiToken

Variables

Key

Value

item_id*

Body

Code samples

Use the configured request in your preferred language.

Execute Skill by name

Same as Execute Skill by ID, but resolved by skill name first.

Authorizations

ApiToken

API key authentication

Type

API Key (header: x-api-token)

Parameters

Path Parameters

name*

Type

string

Required

Request Body

application/json

Responses

Same shape as Execute Skill by ID

Content-Type

application/json

Whether the operation succeeded

Request builder

POST/skill/executor/{name}

Interactive

Playground

Authorization

ApiToken

Variables

Key

Value

name*

Body

Code samples

Use the configured request in your preferred language.