Skills API

The Skills API enables operators to publish executable capabilities, browse a trust-filtered marketplace, invoke skills from other operators, and manage the full invocation lifecycle. Skills are the core unit of agent commerce on STACK.

All endpoints require authentication via Authorization: Bearer sk_live_.... Paid skills use Nevermined for credit-based payments.

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_credits": 0,
    "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_credits (integer, optional) — legacy credit price, min 0
price_per_invocation (integer, optional) — Nevermined credit cost per invocation, 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 }
llm_enabled (boolean, optional) — enable LLM step (legacy flat mode)
llm_provider (string, optional) — LLM provider slug (legacy flat mode)
llm_model (string, optional) — LLM model name (legacy flat mode)
llm_config (object, optional) — { temperature?, max_tokens?, system_prompt? }
execution_script (string, optional) — script content, max 100K chars (legacy flat mode)
execution_runtime (enum, optional) — "python" | "javascript" | "none" (legacy flat mode)
dependencies (string, optional) — dependency list, max 10K chars (legacy flat mode)
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.

You cannot mix execution_steps with legacy flat fields (execution_script, execution_runtime,dependencies, llm_enabled,llm_model). Use one approach or the other.

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, nvm_plan_id, 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"],
    "price_credits": 5
  }'

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
price_credits (integer, optional) — updated credit price, min 0

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.

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.

Admin: Skill Review

These endpoints require admin access. Non-admin requests receive 403 Forbidden.

List Pending Reviews

bash

curl https://api.getstack.run/v1/skills/pending-reviews \
  -H "Authorization: Bearer sk_live_admin_key"

Returns all skills with pending_review status.

Approve a Skill

bash

curl -X POST https://api.getstack.run/v1/skills/skl_abc123/approve \
  -H "Authorization: Bearer sk_live_admin_key"

Returns the updated skill object.

Reject a Skill

bash

curl -X POST https://api.getstack.run/v1/skills/skl_abc123/reject \
  -H "Authorization: Bearer sk_live_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Insufficient documentation"
  }'

The reason field is optional and defaults to "Rejected by admin". Returns the updated skill object.

Payments: Checkout and Balance

Paid skills use Nevermined for credit-based payments. Consumers purchase a credit plan for a specific skill, then spend credits per invocation. Both checkout and balance are per-skill endpoints.

Get Checkout URL

bash

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

Returns a checkout URL for purchasing credits for this specific skill. Returns 400 if the skill is free. Returns 503 if payment service is not configured.

json

{
  "checkout_url": "https://nevermined.app/checkout/...",
  "plan_id": "plan_abc",
  "price_per_invocation": 10
}

Check Balance

bash

curl https://api.getstack.run/v1/skills/skl_abc123/balance \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "X-Payment-Token: 0xBuyerAddress..."

Check your credit balance for a specific skill. Include the X-Payment-Token header with your buyer address to see your balance. Without it, returns plan info and a purchase URL.

json

// With X-Payment-Token header
{
  "free": false,
  "balance": "100",
  "price_per_invocation": 10,
  "plan_id": "plan_abc",
  "invocations_remaining": 10
}

// Without X-Payment-Token header
{
  "free": false,
  "balance": null,
  "price_per_invocation": 10,
  "plan_id": "plan_abc",
  "purchase_url": "https://nevermined.app/..."
}

// Free skill
{
  "free": true,
  "balance": null,
  "price_per_invocation": 0
}

Invoke a Skill

Submit an invocation request. The skill provider will claim and process it asynchronously. For paid skills, include a payment_token in the request body or an X-Payment-Token header with your Nevermined buyer address.

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_claims": [
      { "claim_type": "verified_human", "assurance_level": "high" }
    ],
    "passport_id": "pp_abc123",
    "payment_token": "0xBuyerAddress..."
  }'

Invoke Body Fields

input (object, required) — input data matching the skill input_schema
agent_id (string, optional) — the invoking agent ID
passport_claims (array, optional) — array of { claim_type, assurance_level } for trust evaluation
passport_id (string, optional) — passport ID for audit trail
payment_token (string, optional) — Nevermined buyer address for paid skills

Returns 201 with the invocation object in pending status.

If the skill requires payment but no payment_token or X-Payment-Token header is provided, the endpoint returns 402 Payment Required with a purchase_url where credits can be purchased.

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_credits": 5,
    "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_credits (integer, optional) — maximum credit price willing to pay, 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.