API Documentation — Skills Forest

Authentication

All requests require a Bearer token in the Authorization header. Create tokens from your account’s API Tokens page (profile menu).

Header

Authorization: Bearer YOUR_API_TOKEN

Creating a token: Log in → API Tokens → Create API Token. Choose skill:read, skill:create, and/or skill:delete. Copy the token once — it won’t be shown again.

Base URL

https://skillsforest.ai/api/v1

Endpoints

GET /api/v1/skills List your skills (paginated)

Required ability: skill:read

Example request:

curl -X GET https://skillsforest.ai/api/v1/skills \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Example response (200):

{
  "data": [
    {
      "id": 1,
      "name": "My Skill",
      "slug": "my-skill",
      "description": "A helpful skill",
      "code_content": "Do the thing...",
      "parameters": [],
      "examples": [],
      "is_public": true,
      "source_url": null,
      "source_path": null,
      "files": {
        "scripts": [],
        "references": [],
        "assets": []
      },
      "created_at": "2026-02-11T12:00:00.000000Z",
      "updated_at": "2026-02-11T12:00:00.000000Z"
    }
  ],
  "links": { ... },
  "meta": { ... }
}

GET /api/v1/skills/{id} Get a single skill

Required ability: skill:read. You can view your own skills and any public skill.

Example request:

curl -X GET https://skillsforest.ai/api/v1/skills/1 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Example response (200):

{
  "data": {
    "id": 1,
    "name": "My Skill",
    "slug": "my-skill",
    "description": "A helpful skill",
    "code_content": "Do the thing...",
    "parameters": [],
    "examples": [],
    "is_public": true,
    "source_url": null,
    "source_path": null,
    "files": {
      "scripts": [],
      "references": [
        {
          "path": "references/GUIDE.md",
          "filename": "GUIDE.md",
          "type": "reference",
          "content": "# Guide\n\nUseful reference...",
          "github_url": null,
          "size": 30
        }
      ],
      "assets": []
    },
    "created_at": "2026-02-11T12:00:00.000000Z",
    "updated_at": "2026-02-11T12:00:00.000000Z"
  }
}

POST /api/v1/skills Create a skill

Required ability: skill:create

Body (JSON): name (required), description, code_content, parameters, examples, is_public, files (optional array)

Each item in files: type (script, reference, or asset), path (relative file path), content (file text). See Skill Files.

Example request:

curl -X POST https://skillsforest.ai/api/v1/skills \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-review-helper",
    "description": "Assists with code reviews",
    "code_content": "Review the code...",
    "is_public": true,
    "files": [
      {"type": "script", "path": "scripts/lint.sh", "content": "#!/bin/bash\nphpcs ."},
      {"type": "reference", "path": "references/STYLE.md", "content": "# Style Guide\nFollow PSR-12."}
    ]
  }'

Example response (201):

{
  "data": {
    "id": 2,
    "name": "code-review-helper",
    "slug": "code-review-helper",
    "description": "Assists with code reviews",
    "code_content": "Review the code...",
    "files": {
      "scripts": [
        {"path": "scripts/lint.sh", "filename": "lint.sh", "type": "script", "content": "#!/bin/bash\nphpcs .", "github_url": null, "size": 22}
      ],
      "references": [
        {"path": "references/STYLE.md", "filename": "STYLE.md", "type": "reference", "content": "# Style Guide\nFollow PSR-12.", "github_url": null, "size": 28}
      ],
      "assets": []
    },
    ...
  }
}

DELETE /api/v1/skills/{id} Delete a skill

Required ability: skill:delete. You can only delete skills you own.

Example request:

curl -X DELETE https://skillsforest.ai/api/v1/skills/2 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Example response (200):

{"message": "Skill deleted."}

Skill Files

Skills can include supporting files grouped by type, following the Agent Skills specification. Files are returned as a files object with three keys:

Key	Description
scripts	Executable scripts (e.g. shell scripts, Python scripts)
references	Reference documents (e.g. markdown guides, style guides)
assets	Static assets (e.g. templates, config files)

Each file object contains:

Field	Type	Description
path	string	Relative file path (e.g. `scripts/run.sh`)
filename	string	The filename portion of the path
type	string	One of `script`, `reference`, or `asset`
content	string	The file's text content
github_url	string\|null	URL to the file on GitHub, if imported from a repository
size	integer	Content size in bytes

Rate Limiting

API requests are rate-limited per authenticated user. If you exceed the limit, the API returns a 429 Too Many Requests response with a Retry-After header.

Limit	Window
60 requests	per minute per user

Rate limit headers included in every response:

X-RateLimit-Limit — Maximum requests per window
X-RateLimit-Remaining — Requests remaining in the current window
Retry-After — Seconds to wait (only on 429 responses)

Error Responses

Errors return JSON with a message field. Validation errors include an errors object.

Status	Meaning
401	Missing or invalid token
403	Token lacks ability or no permission on resource
404	Skill not found
422	Validation error — check `errors`
429	Rate limit exceeded — wait and retry after the `Retry-After` period

Token Abilities

Ability	Grants access to
skill:read	GET /api/v1/skills, GET /api/v1/skills/{id}
skill:create	POST /api/v1/skills
skill:delete	DELETE /api/v1/skills/{id}