API Endpoints

This page lists all available endpoints in the systemprompt.io REST API. Every path is relative to the base URL https://systemprompt.io/api/v1/. All requests require authentication via a bearer token in the Authorization header. See API Authentication for details.

Skills

Skills are reusable AI capabilities that define what an agent can do. Each skill contains instructions, parameters, and configuration that shape the AI's behavior for a specific task.

Method	Path	Description
GET	/skills	List all skills
POST	/skills	Create a new skill
GET	/skills/{skill_id}	Retrieve a skill by ID
PUT	/skills/{skill_id}	Replace a skill entirely
PATCH	/skills/{skill_id}	Update specific fields on a skill
DELETE	/skills/{skill_id}	Delete a skill

Example: List All Skills

Request

curl https://systemprompt.io/api/v1/skills \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "items": [
    {
      "id": "sk_abc123",
      "name": "Customer Support Responder",
      "description": "Responds to customer inquiries using product knowledge base",
      "status": "active",
      "created_at": "2026-02-20T10:30:00Z",
      "updated_at": "2026-02-22T14:15:00Z"
    },
    {
      "id": "sk_def456",
      "name": "Content Summarizer",
      "description": "Summarizes long-form content into key bullet points",
      "status": "active",
      "created_at": "2026-02-18T08:00:00Z",
      "updated_at": "2026-02-18T08:00:00Z"
    }
  ],
  "total": 2,
  "page": 1,
  "per_page": 20
}

Example: Create a Skill

Request

curl -X POST https://systemprompt.io/api/v1/skills \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email Drafter",
    "description": "Drafts professional email responses based on context and tone guidelines",
    "instructions": "You are a professional email writer. Match the requested tone and keep responses concise.",
    "parameters": {
      "tone": { "type": "string", "enum": ["formal", "friendly", "neutral"] },
      "max_length": { "type": "integer", "default": 500 }
    }
  }'

Response

{
  "id": "sk_ghi789",
  "name": "Email Drafter",
  "description": "Drafts professional email responses based on context and tone guidelines",
  "instructions": "You are a professional email writer. Match the requested tone and keep responses concise.",
  "parameters": {
    "tone": { "type": "string", "enum": ["formal", "friendly", "neutral"] },
    "max_length": { "type": "integer", "default": 500 }
  },
  "status": "active",
  "created_at": "2026-02-24T12:00:00Z",
  "updated_at": "2026-02-24T12:00:00Z"
}

Agents

Agents are AI-powered workers that use skills to complete tasks. An agent can have one or more skills assigned to it and can be connected to plugins for external integrations.

Method	Path	Description
GET	/agents	List all agents
POST	/agents	Create a new agent
GET	/agents/{agent_id}	Retrieve an agent by ID
PUT	/agents/{agent_id}	Replace an agent entirely
PATCH	/agents/{agent_id}	Update specific fields on an agent
DELETE	/agents/{agent_id}	Delete an agent
GET	/agents/{agent_id}/skills	List skills assigned to an agent
POST	/agents/{agent_id}/skills	Assign a skill to an agent
DELETE	/agents/{agent_id}/skills/{skill_id}	Remove a skill from an agent

Example: Create an Agent

curl -X POST https://systemprompt.io/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Handles customer support inquiries",
    "skill_ids": ["sk_abc123"]
  }'

Plugins

Plugins extend the platform with additional capabilities. They provide tools, data sources, and integrations that agents can use during task execution.

Method	Path	Description
GET	/plugins	List all installed plugins
POST	/plugins	Install a plugin
GET	/plugins/{plugin_id}	Retrieve a plugin by ID
PATCH	/plugins/{plugin_id}	Update plugin configuration
DELETE	/plugins/{plugin_id}	Uninstall a plugin
GET	/plugins/{plugin_id}/config	Retrieve plugin configuration
PUT	/plugins/{plugin_id}/config	Replace plugin configuration

Example: List Installed Plugins

curl https://systemprompt.io/api/v1/plugins \
  -H "Authorization: Bearer YOUR_API_KEY"

Content

Content endpoints let you manage text, documents, and other content items stored on the platform. Agents can reference content as knowledge sources.

Method	Path	Description
GET	/content	List all content items
POST	/content	Create a content item
GET	/content/{content_id}	Retrieve a content item by ID
PUT	/content/{content_id}	Replace a content item
PATCH	/content/{content_id}	Update specific fields on a content item
DELETE	/content/{content_id}	Delete a content item

Example: Create a Content Item

curl -X POST https://systemprompt.io/api/v1/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product FAQ",
    "body": "Frequently asked questions about our product line.",
    "tags": ["support", "faq"]
  }'

MCP Servers

MCP (Model Context Protocol) server endpoints let you register and manage external tool servers that agents can connect to at runtime.

Method	Path	Description
GET	/mcp/servers	List all registered MCP servers
POST	/mcp/servers	Register a new MCP server
GET	/mcp/servers/{server_id}	Retrieve an MCP server by ID
PATCH	/mcp/servers/{server_id}	Update MCP server configuration
DELETE	/mcp/servers/{server_id}	Remove an MCP server
GET	/mcp/servers/{server_id}/tools	List tools provided by an MCP server

Example: Register an MCP Server

curl -X POST https://systemprompt.io/api/v1/mcp/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Tools",
    "url": "https://tools.example.com/mcp",
    "description": "Internal tool server for data lookups"
  }'

Common Query Parameters

Most list endpoints accept the following query parameters for filtering and pagination:

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	20	Items per page (max 100)
sort	string	created_at	Field to sort by
order	string	desc	Sort direction: asc or desc
search	string	--	Filter results by name or description
status	string	--	Filter by status (e.g., active, inactive)

Example with filtering and pagination:

curl "https://systemprompt.io/api/v1/skills?search=email&status=active&page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Troubleshooting

404 Not Found on a valid-looking path. Check that you are using the correct base URL (/api/v1/) and that the resource ID exists. IDs are case-sensitive.

405 Method Not Allowed. You are using the wrong HTTP method for the endpoint. Check the tables above to confirm the correct method.

422 Validation Error. The request body is missing a required field or contains an invalid value. Read the error message for details on which field failed validation.

Empty list returned when items exist. Check your query parameters. A status or search filter might be excluding results you expect to see. Try removing filters to confirm the items exist, then narrow down.