DOCS / API REFERENCE / SKILLS

Skills API

Use the Skills API to publish capabilities, browse the marketplace, invoke skills, and manage invocations.

Send an operator API key, OAuth access token, or supported agent credential in the Authorization: Bearer header. Publishing and lifecycle changes refuse agent contexts. Paid skills are billed from the buyer's STACK wallet in US cents; publishers are paid through Stripe Connect.

Publish a Skill

Register a new skill in the marketplace. The skill name must be in slug format (lowercase alphanumeric with hyphens, 2-64 chars). Skills define input/output schemas in JSON Schema format, an execution mode, trust level requirement, and optional pricing.

bash

curl -X POST https://api.getstack.run/v1/skills \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pdf-summarizer",
    "description": "Summarizes PDF documents using LLM",
    "version": "1.0.0",
    "input_schema": {
      "type": "object",
      "properties": { "url": { "type": "string" } },
      "required": ["url"]
    },
    "output_schema": {
      "type": "object",
      "properties": { "summary": { "type": "string" } }
    },
    "trust_level_required": "L1",
    "tags": ["pdf", "summarization"],
    "price_per_invocation": 10,
    "agent_id": "agt_abc123",
    "execution_mode": "sealed",
    "credential_mode": "buyer_provides",
    "required_credentials": [
      { "provider": "openai", "scopes": ["chat"] }
    ],
    "execution_steps": [
      {
        "type": "script",
        "label": "fetch-pdf",
        "runtime": "javascript",
        "script": "const resp = await fetch(input.url); ..."
      },
      {
        "type": "llm",
        "label": "summarize",
        "llm_provider": "openai",
        "llm_model": "gpt-4o",
        "llm_config": {
          "temperature": 0.3,
          "max_tokens": 2000,
          "system_prompt": "Summarize the following document."
        }
      }
    ]
  }'

PublishSkillInput Fields

name (string, required) - slug format, 2-64 chars, lowercase alphanumeric with hyphens
description (string, required) - 1-1000 chars
version (string, required) - semver format e.g. "1.0.0"
input_schema (object, required) - JSON Schema for skill input
output_schema (object, required) - JSON Schema for skill output
trust_level_required (enum, required) - "L0" | "L1" | "L2"
tags (string[], optional) - up to 10 tags, max 32 chars each, defaults to []
price_per_invocation (integer, optional) - price in USD cents per invocation (e.g. 10 = $0.10), min 0
agent_id (string, optional) - agent ID that provides this skill
execution_mode (enum, optional) - "open" | "sealed" | "source", defaults to "open"
credential_mode (enum, optional) - "none" | "buyer_provides" | "seller_provides" | "both", defaults to "none"
required_credentials (array, optional) - array of { provider: string, scopes: string[] }
seller_credential_limit (object, optional) - { max_calls?: number, max_cost_credits?: number }
accepts_requests (boolean, optional) - whether skill accepts request board matches
execution_steps (array, optional) - multi-step pipeline, 1-10 steps, max 500K total script chars

Execution Steps

Each step in execution_steps is either a script step or an llm step. Script steps define a runtime and script content. LLM steps specify a provider, model, and configuration.

Execution Modes

Sealed - STACK executes the skill internally. The consumer never sees the implementation.

Open - The skill is a contract only. The provider claims invocations and processes them externally.

Source - The skill code is visible and inspectable before invocation.

Returns 201 with the created skill object.

Browse Skills

Search and filter the skill marketplace. All query parameters are optional.

bash

curl "https://api.getstack.run/v1/skills?search=pdf&trust_level=L0&status=active&tags=summarization&limit=20&offset=0" \
  -H "Authorization: Bearer sk_live_your_key"

Query Parameters (BrowseSkillsQuery)

search (string) - free-text search across skill name and description
status (enum) - "active" | "suspended" | "unlisted" | "pending_review"
trust_level (enum) - "L0" | "L1" | "L2"
tags (string[]) - filter by tags
limit (integer) - 1-100, default 20
offset (integer) - pagination offset, default 0

Get Skill Details

bash

curl https://api.getstack.run/v1/skills/skl_abc123 \
  -H "Authorization: Bearer sk_live_your_key"

Returns the full skill object including schemas, average_rating, rating_count, invocation_count, price_per_invocation (USD cents), and timestamps.

List Own Published Skills

bash

curl https://api.getstack.run/v1/skills/mine \
  -H "Authorization: Bearer sk_live_your_key"

Returns all skills published by the authenticated operator.

Update a Skill

Partially update a skill you own. Only the provided fields are changed. The skill name cannot be changed after publication.

bash

curl -X PATCH https://api.getstack.run/v1/skills/skl_abc123 \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description with more detail",
    "version": "1.1.0",
    "trust_level_required": "L0",
    "tags": ["pdf", "ai"]
  }'

UpdateSkillInput Fields

description (string, optional) - 1-1000 chars
version (string, optional) - semver format
input_schema (object, optional) - updated JSON Schema for input
output_schema (object, optional) - updated JSON Schema for output
trust_level_required (enum, optional) - "L0" | "L1" | "L2"
tags (string[], optional) - up to 10 tags, max 32 chars each

Lowering the trust level makes your skill accessible to more agents. Raising it may break existing integrations.

Suspend and Activate Skills

There is no DELETE endpoint for skills. Use suspend to take a skill offline and activate to bring it back. Only the skill owner can perform these actions, and only from a non-agent credential. Activate moves a suspended skill back to active and nothing else: a newly published skill leaves pending_review through review, never through activate.

bash

# Suspend a skill
curl -X POST https://api.getstack.run/v1/skills/skl_abc123/suspend \
  -H "Authorization: Bearer sk_live_your_key"

# Re-activate a skill
curl -X POST https://api.getstack.run/v1/skills/skl_abc123/activate \
  -H "Authorization: Bearer sk_live_your_key"

Both return the updated skill object.

Favorites

Operators can bookmark skills for quick access.

bash

# List your favorite skills
curl https://api.getstack.run/v1/skills/favorites \
  -H "Authorization: Bearer sk_live_your_key"

# Add a skill to favorites
curl -X POST https://api.getstack.run/v1/skills/skl_abc123/favorite \
  -H "Authorization: Bearer sk_live_your_key"

# Remove a skill from favorites
curl -X DELETE https://api.getstack.run/v1/skills/skl_abc123/favorite \
  -H "Authorization: Bearer sk_live_your_key"

Rate a Skill

Submit a rating (1-5) for a skill. Optionally include the invocation ID that prompted the rating. There is no comment field.

bash

curl -X POST https://api.getstack.run/v1/skills/skl_abc123/rate \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5,
    "invocation_id": "sinv_abc123"
  }'

RateSkillInput Fields

rating (integer, required) - 1 to 5
invocation_id (string, optional) - the invocation that prompted this rating

Get Rating Summary

bash

curl https://api.getstack.run/v1/skills/skl_abc123/ratings \
  -H "Authorization: Bearer sk_live_your_key"

Returns the aggregate rating summary for the skill.

Check Trust Level

Evaluate whether a set of passport claims meets a skill's trust requirements before invoking it.

bash

curl -X POST https://api.getstack.run/v1/skills/skl_abc123/check-trust \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "passport_claims": [
      { "claim_type": "verified_human", "assurance_level": "high" }
    ]
  }'

Returns an evaluation object with an allowed boolean indicating whether the claims satisfy the skill's trust_level_required.

Payments: STACK Wallet

Paid skills are billed from the buyer's STACK wallet in USD cents. Buyers top up their wallet via Stripe-hosted checkout; invocations are debited atomically and publisher earnings are credited to the publisher's earnings ledger minus a tier-based commission. Publishers are paid out monthly via Stripe Connect.

See the Billing API docs for the wallet endpoints (/v1/billing/balance, /v1/billing/topup,/v1/billing/refund/:transactionId). The skill endpoints below do not expose payment details - they trust the wallet to have been pre-funded.

Invoke a Skill

Submit an invocation request. The skill provider will claim and process it asynchronously. For paid skills, the caller's STACK wallet must have sufficient balance to coverprice_per_invocation.

bash

curl -X POST https://api.getstack.run/v1/skills/skl_abc123/invoke \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_consumer",
    "input": { "url": "https://example.com/doc.pdf" },
    "passport_id": "pp_abc123"
  }'

Invoke Body Fields

input (object, required) - input data matching the skill input_schema
agent_id (string, optional) - the invoking agent ID
passport_id (string, optional) - passport ID for audit trail

Returns 201 with the invocation object in pending status. Trust claims are resolved server-side from the caller's stored identity claims - they are not passed in the body.

If the wallet has insufficient balance for a paid skill, the endpoint returns 402 withrequired_cents, balance_cents, and atop_up_url pointing at Stripe checkout.

Invocation Lifecycle

Invocations progress through these statuses:

pending - just created, waiting for provider to claim
processing - provider has claimed and is working on it
completed - provider delivered the output
failed - provider reported a failure
expired - TTL exceeded without completion

List Your Invocations (Consumer)

bash

curl https://api.getstack.run/v1/skills/invocations/mine \
  -H "Authorization: Bearer sk_live_your_key"

Returns all invocations you have submitted as a consumer.

Poll for Pending Invocations (Provider)

bash

curl "https://api.getstack.run/v1/skills/invocations/pending?skill_id=skl_abc123" \
  -H "Authorization: Bearer sk_live_your_key"

Returns pending invocations for skills you own. The optional skill_id query parameter filters by a specific skill.

Claim an Invocation (Provider)

bash

curl -X POST https://api.getstack.run/v1/skills/invocations/sinv_abc123/claim \
  -H "Authorization: Bearer sk_live_your_key"

Moves the invocation from pending to processing. Only the skill owner can claim invocations.

Complete an Invocation (Provider)

bash

curl -X POST https://api.getstack.run/v1/skills/invocations/sinv_abc123/complete \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "output": { "summary": "The document discusses..." }
  }'

Marks the invocation as completed with the output data. Only the skill owner can complete invocations.

Get Invocation Result (Consumer)

bash

curl https://api.getstack.run/v1/skills/invocations/sinv_abc123 \
  -H "Authorization: Bearer sk_live_your_key"

Poll this endpoint to check invocation status and retrieve the output once completed. Both the consumer and provider can access this endpoint.

Skill Requests (Request Board)

Operators can post requests describing skills they need. Other operators can browse these requests, find matching skills, and build new skills to fulfill demand.

Post a Skill Request

bash

curl -X POST https://api.getstack.run/v1/skill-requests \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Need a skill that converts CSV files to JSON with schema validation",
    "desired_input_schema": {
      "type": "object",
      "properties": { "csv_url": { "type": "string" } }
    },
    "desired_output_schema": {
      "type": "object",
      "properties": { "json": { "type": "array" } }
    },
    "max_price_cents": 25,
    "tags": ["csv", "json", "conversion"]
  }'

PostSkillRequestInput Fields

description (string, required) - 1-2000 chars describing the desired skill
desired_input_schema (object, optional) - JSON Schema for desired input
desired_output_schema (object, optional) - JSON Schema for desired output
max_price_cents (integer, optional) - maximum price in USD cents willing to pay per invocation, min 0
tags (string[], optional) - up to 10 tags, max 32 chars each, defaults to []

Returns 201 with the created request object.

List Skill Requests

bash

curl "https://api.getstack.run/v1/skill-requests?status=open&limit=20&offset=0" \
  -H "Authorization: Bearer sk_live_your_key"

Query parameters: status (open | closed | fulfilled),limit (max 100), offset. All optional.

Get a Skill Request

bash

curl https://api.getstack.run/v1/skill-requests/sreq_abc123 \
  -H "Authorization: Bearer sk_live_your_key"

Update a Skill Request

bash

curl -X PATCH https://api.getstack.run/v1/skill-requests/sreq_abc123 \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "fulfilled",
    "description": "Updated description"
  }'

Status must be one of: open, closed, fulfilled. Only the request owner can update.

Get Matching Skills for a Request

bash

curl https://api.getstack.run/v1/skill-requests/sreq_abc123/matches \
  -H "Authorization: Bearer sk_live_your_key"

Returns skills that match the request based on tags and schemas.

Suggest Skill Composition

bash

curl https://api.getstack.run/v1/skill-requests/sreq_abc123/suggest \
  -H "Authorization: Bearer sk_live_your_key"

Suggests how existing skills could be composed to fulfill the request.

← PREV: IDENTITY NEXT: TEAM

STACKONE RUNTIME BOUNDARY FOR AI AGENTS.
BUILT IN STOCKHOLM.

$npx @getstackrun/cli setup

ATTACK OUR AGENT

PRODUCTPRODUCT PRICING FOR PLATFORMS INTEGRATIONS

DEVELOPERSDOCS ACCEPT AGENTS SIGN IN

TRUSTSECURITY AGENT SECURITY ATTACK US EU AI ACT ART. 14

COMPANYCONTACT PRIVACY TERMS