Skip to main content
POST
/
api
/
skills
cURL
curl -X POST "https://app.cotool.ai/api/skills" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","description":"string","instructionPrompt":"string","requiredTools":["string"],"references":[{"filename":"string","directory":"references","sizeBytes":0,"content":"string"}]}'
{
  "id": "<string>",
  "organizationId": "<string>",
  "name": "<string>",
  "description": "<string>",
  "requiredTools": [
    "<string>"
  ],
  "createdByUserId": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>",
  "instructionPrompt": "<string>",
  "usedByAgentCount": 123,
  "invocationCount30d": 123,
  "currentVersion": 123,
  "references": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "skillVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "filename": "<string>",
      "directory": "references",
      "sizeBytes": 1,
      "content": "<string>",
      "createdAt": "<string>"
    }
  ]
}

Authorizations

Authorization
string
header
required

API Key authentication for programmatic access. Include your API key in the Authorization header as: Bearer your_api_key_here

Body

application/json
name
string
required

Machine-safe skill name used in sandbox paths and imports

Required string length: 1 - 64
Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
description
string
required

Description of what this skill teaches an agent to do

Minimum string length: 1
instructionPrompt
string
required

Primary instruction prompt content for this skill

Minimum string length: 1
requiredTools
string[]

Optional required tool types for this skill

references
object[]

Optional references for initial version creation

Response

200 - application/json

Successful response

id
string
required

Unique identifier for the skill

organizationId
string
required

Unique identifier of the organization that owns this skill

name
string
required

Machine-safe skill name used in sandbox paths and imports

Required string length: 1 - 64
Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
description
string
required

Description of what this skill teaches an agent to do

requiredTools
string[]
required

Optional required tool types for this skill

createdByUserId
string | null
required

User ID that created this skill, or null for system-created records

createdAt
string
required

Timestamp when the skill was created

updatedAt
string
required

Timestamp when the skill was last updated

deletedAt
string | null
required

Timestamp when the skill was soft-deleted, or null if active

instructionPrompt
string
required

Primary instruction prompt content for this skill

usedByAgentCount
number

How many agents currently use this skill

invocationCount30d
number

Distinct chats in the last 30 days where an agent read this skill from the sandbox

currentVersion
number

Current version number of this skill

references
object[]

Resource files for the active/current version