AGNTDocs

Work

Skills

Packaged capabilities your assistants use: instructions, connected tool servers and recurring workflows.

GET/skills

List skills

Returns the skills available to the caller, with how each is installed for them.

Query parameters

kindstring
qstringSearch name and title
pageinteger
limitinteger

Responses

200Skills
okboolean
skillsobject[]
idstringSkill id
namestringUnique slug
titlestring
descriptionstring
whenToUsestringWhen the assistant should reach for it
instructionsstring
kindenumknowledge: instructions only. mcp: a connected tool server. workflow: a recurring task. plugin and cli: code (account keys only).knowledgemcpcliagentpromptpluginworkflowtask_template
statusenumactivedraftarchived
accessenumpublicprivate
contentVisibilityenumopaque hides the instructions from users who can run the skilltransparentopaque
approvalModeenumautomanual
versionnumber
tagsstring[]
modelTierenumFor workflows: tier of the tasks it starts; null inheritslowmediumhighultranull
defaultEffortenumFor workflows: Reasoning effort: how much thinking the assistant applies on each run, independent of modelTier. low, medium, high, xhigh (extra high) or max. null inherits the account default.lowmediumhighxhighmaxnull
installationobject | nullHow the skill is installed for the caller
idstring
sourcestringown for skills you created
statusenumlivepaused
createdAtstring
updatedAtstring
totalinteger
pageinteger

Request

curl 'https://api.agnt.ai/skills' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "skills": [
    {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "name": "Ava",
      "title": "Send Brightline the contract renewal",
      "description": "Draft it, get Maria to sign off, send it."
    }
  ],
  "total": 42,
  "page": 1
}
POST/skills

Create a skill

Creates a skill. Every kind takes `name`, `title`, `description` and `instructions`. `kind: "workflow"` adds `triggers` and run limits; `kind: "mcp"` takes `mcpServerUrl`, `mcpTransport` and `mcpAuthType`. With an account key alone the skill is available app-wide; with `X-User-Email` it is created for that user only.

Request body

namestringUnique slug. Required, except for kind mcp with mcpServerUrl.
titlestringDisplay name. Required, except for kind mcp with mcpServerUrl.
descriptionstringWhat the skill does, up to 5000 characters. Required, except for kind mcp with mcpServerUrl, task templates and cli skills.
whenToUsestringWhen the assistant should use it
instructionsstringThe content the assistant follows. For kind workflow: what each run does.
kindenumDefaults to agent. knowledge: instructions only. mcp: a connected tool server. workflow: recurring or event-driven work; each firing creates a task. plugin and cli: code (account keys only).knowledgemcpcliagentpromptpluginworkflowtask_template
accessenumpublicprivate
contentVisibilityenumtransparentopaque
approvalModeenumautomanual
tagsstring[]
modelTierenumFor workflows: tier of the tasks it starts; null inheritslowmediumhighultranull
defaultEffortenumFor workflows: Reasoning effort: how much thinking the assistant applies on each run, independent of modelTier. low, medium, high, xhigh (extra high) or max. null inherits the account default.lowmediumhighxhighmaxnull
scheduleTypeenumkind workflow. Inferred from triggers when omitted: recurring with a cron trigger, trigger-based with webhook, timestamp or condition triggers.nowrecurringtrigger-based
triggersobject[]kind workflow: when it fires. Each firing creates a task.
on reqenumcron: a fixed schedule. webhook: a calendar or email event. timestamp: relative to a time on the matched event. condition: when a polled condition becomes true. inactivity: when an expected event did not happen. system: when another workflow or task completes or fails. compound: several sub-triggers with and / or. manual: only when run by hand.cronwebhooktimestampconditioninactivitysystemcompoundmanual
scheduleobjectFor cron
frequency reqenumminutelyhourlydailyweeklymonthly
intervalintegerEvery Nth minute, hour, day, week or month
daysstring[]Weekdays to run on; the string working-days is also accepted
hourinteger
minuteinteger
dayOfMonthintegerFor monthly
timezonestringIANA timezone for schedule, such as America/New_York
categoryenumFor webhook, timestamp and inactivity: which kind of sourcecalendaremail
eventenumFor webhookevent.scheduledevent.rescheduledevent.attendeesUpdatedevent.metadataUpdatedevent.cancelledemail.receivedemail.senttask.completedtask.failedtask.createdworkflow.triggeredworkflow.completedworkflow.failed
conditionPromptstringFor webhook: a plain-language filter the event must also satisfy
delayOffsetobjectFor webhook and system: fire this long after the match
valueinteger
unitenumminuteshoursdays
timestampFieldstringFor timestamp: the event field to anchor to, such as startTime
timestampOffsetobjectFor timestamp: negative is before the anchor
offsetnumber
unitenumminuteshoursdays
naturalConditionstringFor condition: the condition in plain language
pollIntervalobjectFor condition
valuenumber
unitenumminuteshours
inactivityWindowobjectFor inactivity
offsetnumber
unitenumminuteshoursdays
systemEventenumFor systemtask.completedtask.failedtask.createdworkflow.triggeredworkflow.completedworkflow.failed
sourceWorkflowstringFor system: the workflow whose event this listens to
compoundOperatorenumFor compoundandor
subTriggersobject[]For compound: triggers in this same shape
maxRunsinteger | nullkind workflow: stop after this many runs
recurrenceEndsAtstring | nullkind workflow: stop after this time
maxConcurrentintegerkind workflow: runs allowed at once
cooldownMsintegerkind workflow: minimum gap between firings
overflowBehaviorenumkind workflow: what a firing does while maxConcurrent runs are goingqueuedropreplace
mcpServerUrlstringkind mcp: the MCP server URL. With it, name, title and description are optional and are taken from the server when omitted.
mcpTransportenumkind mcp: transport for a remote serverstreamable-httpsse
mcpAuthTypeenumkind mcp: how users authenticate to the servernoneoauthapi_key
mcpRequiredScopesstring[]kind mcp with oauth: scopes to request

Responses

201Skill
okboolean
skillobject
idstringSkill id
namestringUnique slug
titlestring
descriptionstring
whenToUsestringWhen the assistant should reach for it
instructionsstring
kindenumknowledge: instructions only. mcp: a connected tool server. workflow: a recurring task. plugin and cli: code (account keys only).knowledgemcpcliagentpromptpluginworkflowtask_template
statusenumactivedraftarchived
accessenumpublicprivate
contentVisibilityenumopaque hides the instructions from users who can run the skilltransparentopaque
approvalModeenumautomanual
versionnumber
tagsstring[]
modelTierenumFor workflows: tier of the tasks it starts; null inheritslowmediumhighultranull
defaultEffortenumFor workflows: Reasoning effort: how much thinking the assistant applies on each run, independent of modelTier. low, medium, high, xhigh (extra high) or max. null inherits the account default.lowmediumhighxhighmaxnull
installationobject | nullHow the skill is installed for the caller
idstring
sourcestringown for skills you created
statusenumlivepaused
createdAtstring
updatedAtstring
400Invalid body
403Not allowed for this caller, such as an end user creating a plugin or code skill
409A skill with this name exists

Request

curl 'https://api.agnt.ai/skills' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "vendor-approval-policy",
  "title": "Vendor approval policy",
  "description": "Harborview rules for approving vendor quotes",
  "kind": "knowledge",
  "instructions": "Quotes over 5,000 USD need sign-off from Maria Chen before you accept them."
}'

Response

{
  "ok": true,
  "skill": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "name": "Ava",
    "title": "Send Brightline the contract renewal",
    "description": "Draft it, get Maria to sign off, send it."
  }
}
GET/skills/{skillId}

Retrieve a skill

Retrieves a skill by id or name.

Path parameters

skillId reqstring

Responses

200Skill
okboolean
skillobject
idstringSkill id
namestringUnique slug
titlestring
descriptionstring
whenToUsestringWhen the assistant should reach for it
instructionsstring
kindenumknowledge: instructions only. mcp: a connected tool server. workflow: a recurring task. plugin and cli: code (account keys only).knowledgemcpcliagentpromptpluginworkflowtask_template
statusenumactivedraftarchived
accessenumpublicprivate
contentVisibilityenumopaque hides the instructions from users who can run the skilltransparentopaque
approvalModeenumautomanual
versionnumber
tagsstring[]
modelTierenumFor workflows: tier of the tasks it starts; null inheritslowmediumhighultranull
defaultEffortenumFor workflows: Reasoning effort: how much thinking the assistant applies on each run, independent of modelTier. low, medium, high, xhigh (extra high) or max. null inherits the account default.lowmediumhighxhighmaxnull
installationobject | nullHow the skill is installed for the caller
idstring
sourcestringown for skills you created
statusenumlivepaused
createdAtstring
updatedAtstring
404Skill not found

Request

curl 'https://api.agnt.ai/skills/<skillId>' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "skill": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "name": "Ava",
    "title": "Send Brightline the contract renewal",
    "description": "Draft it, get Maria to sign off, send it."
  }
}
PATCH/skills/{skillId}

Update a skill

Updates a skill you created. Only the fields you send change. `skillId` is the id or the name.

Path parameters

skillId reqstring

Request body

namestringUnique slug. Required, except for kind mcp with mcpServerUrl.
titlestringDisplay name. Required, except for kind mcp with mcpServerUrl.
descriptionstringWhat the skill does, up to 5000 characters. Required, except for kind mcp with mcpServerUrl, task templates and cli skills.
whenToUsestringWhen the assistant should use it
instructionsstringThe content the assistant follows. For kind workflow: what each run does.
kindenumDefaults to agent. knowledge: instructions only. mcp: a connected tool server. workflow: recurring or event-driven work; each firing creates a task. plugin and cli: code (account keys only).knowledgemcpcliagentpromptpluginworkflowtask_template
accessenumpublicprivate
contentVisibilityenumtransparentopaque
approvalModeenumautomanual
tagsstring[]
modelTierenumFor workflows: tier of the tasks it starts; null inheritslowmediumhighultranull
defaultEffortenumFor workflows: Reasoning effort: how much thinking the assistant applies on each run, independent of modelTier. low, medium, high, xhigh (extra high) or max. null inherits the account default.lowmediumhighxhighmaxnull
statusenumactivedraftarchived
scheduleTypeenumkind workflow. Inferred from triggers when omitted: recurring with a cron trigger, trigger-based with webhook, timestamp or condition triggers.nowrecurringtrigger-based
triggersobject[]kind workflow: when it fires. Each firing creates a task.
on reqenumcron: a fixed schedule. webhook: a calendar or email event. timestamp: relative to a time on the matched event. condition: when a polled condition becomes true. inactivity: when an expected event did not happen. system: when another workflow or task completes or fails. compound: several sub-triggers with and / or. manual: only when run by hand.cronwebhooktimestampconditioninactivitysystemcompoundmanual
scheduleobjectFor cron
frequency reqenumminutelyhourlydailyweeklymonthly
intervalintegerEvery Nth minute, hour, day, week or month
daysstring[]Weekdays to run on; the string working-days is also accepted
hourinteger
minuteinteger
dayOfMonthintegerFor monthly
timezonestringIANA timezone for schedule, such as America/New_York
categoryenumFor webhook, timestamp and inactivity: which kind of sourcecalendaremail
eventenumFor webhookevent.scheduledevent.rescheduledevent.attendeesUpdatedevent.metadataUpdatedevent.cancelledemail.receivedemail.senttask.completedtask.failedtask.createdworkflow.triggeredworkflow.completedworkflow.failed
conditionPromptstringFor webhook: a plain-language filter the event must also satisfy
delayOffsetobjectFor webhook and system: fire this long after the match
valueinteger
unitenumminuteshoursdays
timestampFieldstringFor timestamp: the event field to anchor to, such as startTime
timestampOffsetobjectFor timestamp: negative is before the anchor
offsetnumber
unitenumminuteshoursdays
naturalConditionstringFor condition: the condition in plain language
pollIntervalobjectFor condition
valuenumber
unitenumminuteshours
inactivityWindowobjectFor inactivity
offsetnumber
unitenumminuteshoursdays
systemEventenumFor systemtask.completedtask.failedtask.createdworkflow.triggeredworkflow.completedworkflow.failed
sourceWorkflowstringFor system: the workflow whose event this listens to
compoundOperatorenumFor compoundandor
subTriggersobject[]For compound: triggers in this same shape
maxRunsinteger | nullkind workflow: stop after this many runs
recurrenceEndsAtstring | nullkind workflow: stop after this time
maxConcurrentintegerkind workflow: runs allowed at once
cooldownMsintegerkind workflow: minimum gap between firings
overflowBehaviorenumkind workflow: what a firing does while maxConcurrent runs are goingqueuedropreplace
mcpServerUrlstringkind mcp: the MCP server URL. With it, name, title and description are optional and are taken from the server when omitted.
mcpTransportenumkind mcp: transport for a remote serverstreamable-httpsse
mcpAuthTypeenumkind mcp: how users authenticate to the servernoneoauthapi_key
mcpRequiredScopesstring[]kind mcp with oauth: scopes to request

Responses

200Skill
okboolean
skillobject
idstringSkill id
namestringUnique slug
titlestring
descriptionstring
whenToUsestringWhen the assistant should reach for it
instructionsstring
kindenumknowledge: instructions only. mcp: a connected tool server. workflow: a recurring task. plugin and cli: code (account keys only).knowledgemcpcliagentpromptpluginworkflowtask_template
statusenumactivedraftarchived
accessenumpublicprivate
contentVisibilityenumopaque hides the instructions from users who can run the skilltransparentopaque
approvalModeenumautomanual
versionnumber
tagsstring[]
modelTierenumFor workflows: tier of the tasks it starts; null inheritslowmediumhighultranull
defaultEffortenumFor workflows: Reasoning effort: how much thinking the assistant applies on each run, independent of modelTier. low, medium, high, xhigh (extra high) or max. null inherits the account default.lowmediumhighxhighmaxnull
installationobject | nullHow the skill is installed for the caller
idstring
sourcestringown for skills you created
statusenumlivepaused
createdAtstring
updatedAtstring
403Not your skill
404Skill not found

Request

curl 'https://api.agnt.ai/skills/<skillId>' \
  -X PATCH \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "instructions": "Quotes over 10,000 USD need sign-off from Maria Chen before you accept them."
}'

Response

{
  "ok": true,
  "skill": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "name": "Ava",
    "title": "Send Brightline the contract renewal",
    "description": "Draft it, get Maria to sign off, send it."
  }
}
PUT/skills/{skillId}

Update a skill

Updates a skill you created. Only the fields you send change. `skillId` is the id or the name.

Path parameters

skillId reqstring

Request body

namestringUnique slug. Required, except for kind mcp with mcpServerUrl.
titlestringDisplay name. Required, except for kind mcp with mcpServerUrl.
descriptionstringWhat the skill does, up to 5000 characters. Required, except for kind mcp with mcpServerUrl, task templates and cli skills.
whenToUsestringWhen the assistant should use it
instructionsstringThe content the assistant follows. For kind workflow: what each run does.
kindenumDefaults to agent. knowledge: instructions only. mcp: a connected tool server. workflow: recurring or event-driven work; each firing creates a task. plugin and cli: code (account keys only).knowledgemcpcliagentpromptpluginworkflowtask_template
accessenumpublicprivate
contentVisibilityenumtransparentopaque
approvalModeenumautomanual
tagsstring[]
modelTierenumFor workflows: tier of the tasks it starts; null inheritslowmediumhighultranull
defaultEffortenumFor workflows: Reasoning effort: how much thinking the assistant applies on each run, independent of modelTier. low, medium, high, xhigh (extra high) or max. null inherits the account default.lowmediumhighxhighmaxnull
statusenumactivedraftarchived
scheduleTypeenumkind workflow. Inferred from triggers when omitted: recurring with a cron trigger, trigger-based with webhook, timestamp or condition triggers.nowrecurringtrigger-based
triggersobject[]kind workflow: when it fires. Each firing creates a task.
on reqenumcron: a fixed schedule. webhook: a calendar or email event. timestamp: relative to a time on the matched event. condition: when a polled condition becomes true. inactivity: when an expected event did not happen. system: when another workflow or task completes or fails. compound: several sub-triggers with and / or. manual: only when run by hand.cronwebhooktimestampconditioninactivitysystemcompoundmanual
scheduleobjectFor cron
frequency reqenumminutelyhourlydailyweeklymonthly
intervalintegerEvery Nth minute, hour, day, week or month
daysstring[]Weekdays to run on; the string working-days is also accepted
hourinteger
minuteinteger
dayOfMonthintegerFor monthly
timezonestringIANA timezone for schedule, such as America/New_York
categoryenumFor webhook, timestamp and inactivity: which kind of sourcecalendaremail
eventenumFor webhookevent.scheduledevent.rescheduledevent.attendeesUpdatedevent.metadataUpdatedevent.cancelledemail.receivedemail.senttask.completedtask.failedtask.createdworkflow.triggeredworkflow.completedworkflow.failed
conditionPromptstringFor webhook: a plain-language filter the event must also satisfy
delayOffsetobjectFor webhook and system: fire this long after the match
valueinteger
unitenumminuteshoursdays
timestampFieldstringFor timestamp: the event field to anchor to, such as startTime
timestampOffsetobjectFor timestamp: negative is before the anchor
offsetnumber
unitenumminuteshoursdays
naturalConditionstringFor condition: the condition in plain language
pollIntervalobjectFor condition
valuenumber
unitenumminuteshours
inactivityWindowobjectFor inactivity
offsetnumber
unitenumminuteshoursdays
systemEventenumFor systemtask.completedtask.failedtask.createdworkflow.triggeredworkflow.completedworkflow.failed
sourceWorkflowstringFor system: the workflow whose event this listens to
compoundOperatorenumFor compoundandor
subTriggersobject[]For compound: triggers in this same shape
maxRunsinteger | nullkind workflow: stop after this many runs
recurrenceEndsAtstring | nullkind workflow: stop after this time
maxConcurrentintegerkind workflow: runs allowed at once
cooldownMsintegerkind workflow: minimum gap between firings
overflowBehaviorenumkind workflow: what a firing does while maxConcurrent runs are goingqueuedropreplace
mcpServerUrlstringkind mcp: the MCP server URL. With it, name, title and description are optional and are taken from the server when omitted.
mcpTransportenumkind mcp: transport for a remote serverstreamable-httpsse
mcpAuthTypeenumkind mcp: how users authenticate to the servernoneoauthapi_key
mcpRequiredScopesstring[]kind mcp with oauth: scopes to request

Responses

200Skill
okboolean
skillobject
idstringSkill id
namestringUnique slug
titlestring
descriptionstring
whenToUsestringWhen the assistant should reach for it
instructionsstring
kindenumknowledge: instructions only. mcp: a connected tool server. workflow: a recurring task. plugin and cli: code (account keys only).knowledgemcpcliagentpromptpluginworkflowtask_template
statusenumactivedraftarchived
accessenumpublicprivate
contentVisibilityenumopaque hides the instructions from users who can run the skilltransparentopaque
approvalModeenumautomanual
versionnumber
tagsstring[]
modelTierenumFor workflows: tier of the tasks it starts; null inheritslowmediumhighultranull
defaultEffortenumFor workflows: Reasoning effort: how much thinking the assistant applies on each run, independent of modelTier. low, medium, high, xhigh (extra high) or max. null inherits the account default.lowmediumhighxhighmaxnull
installationobject | nullHow the skill is installed for the caller
idstring
sourcestringown for skills you created
statusenumlivepaused
createdAtstring
updatedAtstring
403Not your skill
404Skill not found

Request

curl 'https://api.agnt.ai/skills/<skillId>' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "instructions": "Quotes over 10,000 USD need sign-off from Maria Chen before you accept them."
}'

Response

{
  "ok": true,
  "skill": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "name": "Ava",
    "title": "Send Brightline the contract renewal",
    "description": "Draft it, get Maria to sign off, send it."
  }
}
POST/skills/{skillId}/publish

Publish a skill

Saves the skill's current content as a new version. Pass `deploy` to make that version live in `environment`. `skillId` must be the id.

Path parameters

skillId reqstring

Request body

environment reqstringEnvironment slug
deployboolean
notestringRelease note

Responses

200Published
okboolean
publishobject
versionNumbernumber
etagstring
skillobject
idstringSkill id
namestringUnique slug
titlestring
descriptionstring
whenToUsestringWhen the assistant should reach for it
instructionsstring
kindenumknowledge: instructions only. mcp: a connected tool server. workflow: a recurring task. plugin and cli: code (account keys only).knowledgemcpcliagentpromptpluginworkflowtask_template
statusenumactivedraftarchived
accessenumpublicprivate
contentVisibilityenumopaque hides the instructions from users who can run the skilltransparentopaque
approvalModeenumautomanual
versionnumber
tagsstring[]
modelTierenumFor workflows: tier of the tasks it starts; null inheritslowmediumhighultranull
defaultEffortenumFor workflows: Reasoning effort: how much thinking the assistant applies on each run, independent of modelTier. low, medium, high, xhigh (extra high) or max. null inherits the account default.lowmediumhighxhighmaxnull
installationobject | nullHow the skill is installed for the caller
idstring
sourcestringown for skills you created
statusenumlivepaused
createdAtstring
updatedAtstring
400Missing environment, skillId is a name rather than an id, or the publish failed
404Skill not found

Request

curl 'https://api.agnt.ai/skills/<skillId>/publish' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "environment": "production"
}'

Response

{
  "ok": true,
  "publish": {
    "versionNumber": 1,
    "etag": "etag",
    "skill": {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "name": "Ava",
      "title": "Send Brightline the contract renewal",
      "description": "Draft it, get Maria to sign off, send it."
    }
  }
}