Skip to main content
POST
Python SDK

Access

This operation needs a Parable token. An MCP token cannot call it. See Authentication for the kinds of token. Your roles must grant tenant.parables.manage.

Errors

  • HTTP 400: The Agent Skill input is invalid. Correct the name, metadata, instructions, or idempotency key.
  • HTTP 401: The request is not authenticated. Sign in and select the Workspace.
  • HTTP 403: You cannot manage Agent Skills in this Workspace. Use a Workspace where you can manage Parables.
  • HTTP 409: The name is already used or the idempotency key belongs to different instructions. Reuse the original request unchanged, or choose a new name and idempotency key for a deliberately new Skill.

Authorizations

Authorization
string
header
required

A personal access token, which starts with pat_. A Parable token can call each operation that the roles of its owner allow. An MCP token can call only the read operations that are open to agents. A SQL token does not work on this API.

Headers

X-Tenant
string

Workspace slug. Overrides subdomain-based workspace resolution when provided.

Example:

"acme"

X-Request-ID
string<uuid>

Optional request correlation ID echoed back in the response.

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json
content
string
required

Markdown text

Required string length: 1 - 65536
Pattern: ^[\s\S]*$
description
string
required
Required string length: 1 - 1024
displayTitle
string
required
Required string length: 1 - 80
files
object[]
required
Maximum array length: 400
icon
string
required

Serialized icon spec: a Font Awesome pack/weight/fill/name, an emoji, or an asset URL

Required string length: 1 - 2048
Pattern: ^(?:fa:[a-z0-9]+(?:-[a-z0-9]+)*:[a-z0-9]+-[a-z0-9]+(?:-[a-z0-9]+)*:[a-z0-9]+(?:-[a-z0-9]+)*(?:@#[0-9a-f]{6})?|emoji:\S+|image:\S+)$
idempotencyKey
string
required

UUID v4 with automatic base62 encoding for client-facing APIs

Pattern: ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
name
string
required

Portable Agent Skills directory and frontmatter name

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

Response

Successful response

data
object
required

Mutable Workspace catalog entry used by the API and authoring UI.

meta
object
required