Documentation
OpenAPI 1.0.0

API reference

Every operation of the catalogue, the REST routes, authentication, limits and every error code.

One catalogue, three ways in

Everything the dashboard shows and does is an operation of one catalogue. Each operation is a tool of the hosted MCP server, a POST https://skillhook.dev/api/v1/tools/{name} over REST, and a skillhook cloud <name> command in a terminal. GET /api/v1/tools lists them with their JSON Schema, the scope each needs and whether your key has it; the resource routes below map onto the dashboard's pages for callers who prefer nouns. The whole thing is also an OpenAPI 3.1 document (how to use it).

Authentication and scopes

Every request carries an organisation API key (shc_…, created by an admin under Settings → API keys, shown once and stored hashed) as Authorization: Bearer. Never put a key in a URL. A key acts as the role its scope names; API keys and scopes has the details.

ScopeTypeDescription
fleet:read
viewer
Reads: the overview, stats, alerts, machines, skills, jobs, deliveries, hosted URLs (not the URLs), commands, settings, members, problem reports.
fleet:run
member
Also acts: skill sources, job files, live output, hosted URLs; run and test skills, answer agents, replay, cancel, dismiss alerts.
fleet:admin
admin
Also changes: the audit log, notification channels (read and test); save and delete skills, hosted URLs on and off, rename and disconnect machines, settings, configuration, restarts, updates, secrets.

Conventions

  • Machines pull. An action is queued as a command the machine runs on its next sync (seconds while it is online, up to ten minutes while it is not). Routes that wait answer 202 with pending: true while the machine has not answered; GET /api/v1/commands/{id}?wait=30 follows it.
  • Names or ids. A machine is named by id, name or hostname; a job or delivery by the cloud's id or the machine's own. An ambiguous name is a 409 naming the id to use.
  • Paging. Lists are newest first and return next_before; send it back as before for the next page. limit is at most 100.
  • Idempotency. POST /api/v1/issues takes an Idempotency-Key (the same key from the same API key returns the original report). Runs, replays and commands take one too: the Idempotency-Key header on POST …/skills/{skill}/run, …/replay and …/commands, or idempotency_key in the tool input; a retry with the same key within 24 hours returns the command the first call queued (idempotent_replay: true) instead of running it twice, and the same key for a different request answers 409 idempotency_conflict. Everything else is idempotent by nature.
  • Limits. 600 requests a minute per key (429 rate_limited with Retry-After); bodies up to 512 KiB (768 KiB for a whole SKILL.md and on the MCP server).
  • Request ids. Every answer carries x-request-id (send your own, 1–128 characters of letters, digits, ._:-); quote it when you report a problem.

The catalogue

59 operations. Each takes a JSON object (its input_schema) and answers JSON; a refusal is a problem (below) over REST and an error result over MCP. The scope column is the least a key needs; a command the operation queues may need more (send_command with logs.tail needs fleet:admin).

OperationScopeWhat
describe_cloudreads
fleet:read
Overview: what needs attentionCall this first. The organisation, this key's scopes, its role and whose access it carries (acts_for: its creator, or null once they left); every machine it can see (status, mode, runners not ready); what needs a person now: agents waiting for an answer (with their question), open alerts, failing or warning health checks, jobs that failed, webhooks rejected and Cloud timer slots skipped (with why and the fix) in the last 24 hours; the day's numbers (jobs, cost, deliveries); and next_steps naming the tools that act on each. With no machine paired yet, get_started gives the page and the three commands that pair one, to show the person as they are; once one is paired but no skill beyond the hello smoke test has run, first_automation walks through the person's first automation from the conversation (ideas, test_skill, save_skill, enable_hosted_url or save_schedule). After asking get_started.ask_the_person, call it again with answer (yes, no or unsure): get_started.answered gives the step that fits.
get_statsreads
fleet:read
StatisticsThe Stats page for every machine: per day of the window, jobs (succeeded, failed, needing a person), agent cost, tokens, p50/p95 duration and deliveries (accepted, rejected, skipped, via hosted URLs); totals with the success rate; and each skill's runs, failures, cost, p95 and last run.
list_alertsreads
fleet:read
List alertsConditions worth a person's attention, newest first: an agent waiting for a person (needs_human), a machine gone offline, a failed job, a failing health check. They resolve themselves when the condition clears. state: resolved lists recently resolved ones.
dismiss_alertacts, irreversibly
fleet:run
Dismiss an alertResolve an open alert by hand (it opens again only if its condition clears and recurs). Alerts also resolve themselves: answering a waiting agent resolves its needs_human alert, and a later successful run of the same skill on the same machine resolves its earlier job_failed alerts.
list_machinesreads
fleet:read
List machinesEvery paired machine: status (online, degraded, offline), mode (observe = read-only, control = accepts actions), link state, runner readiness, health summary, skillhook version, last seen.
get_machinereads
fleet:read
Get a machineOne machine as its page shows it: the link (last sync, clock skew, events waiting), its policy (mode, allow/deny lists), failing or warning health checks with their fix, runner readiness, skills (and those that failed to load), schedules, linked repositories, running jobs, a day of its own stats and its account pool (account_pool: how it picks, and each Claude Code / Codex account's status and usage windows as of now, a window that has reset counting as empty); for admin keys its skillhook.json as last reported.
rename_machineacts, irreversibly
fleet:admin
Rename a machineChange the name the cloud shows for a machine (its hostname stays what it reports).
disconnect_machineacts, irreversibly
fleet:admin
Disconnect a machineRevoke a machine's token and cancel its pending commands: it stops syncing at once. Its history stays; pairing again creates a new machine. Confirm with the person first.
list_skillsreads
fleet:read
List skillsSkills on every machine (or one): runner, model, auth type and whether its secret is set, when-filters, schedule, whether webhooks reach it, its hosted URL (on/off, never the URL) and its last job.
get_skillreads
fleet:run
Read a skill's SKILL.mdA skill's summary and its SKILL.md fetched from the machine (the machine must be online). Edit the content and save it with save_skill.
save_skillacts, irreversibly
fleet:admin
Save a skillWrite skills/<skill>/SKILL.md on a machine, creating or replacing it; the machine validates it first and answers with the error when it is invalid. Not for hooks from a linked repository (change those in the repository). auth: none needs allow_unauthenticated. No secret is created: use the dashboard or `skillhook cloud secret` for that. Try a draft with test_skill first.
delete_skillacts, irreversibly
fleet:admin
Delete a skillRemove a skill from a machine's skills/ (moved to jobs/.removed-skills/ there, where it can be restored). Its webhook answers 404 from then on. Confirm with the person first.
run_skillacts, irreversibly
fleet:run
Run a skillRun an installed skill on a machine as if a webhook arrived with this payload (no signature check, no filters). wait_seconds waits for the job to finish or to ask a person.
test_skillacts, irreversibly
fleet:run
Test a SKILL.mdRun a SKILL.md once on a machine without installing it (trigger test), to try a skill before save_skill.
list_inboxreads
fleet:read
The inboxWhat the agents need from a person, what they are doing and what they did, as the dashboard's Inbox shows it. Per job: title (what the agent called it), state (needs_input, in_progress, done, failed), progress (message, percent, step, with recent_updates while it runs), headline (the result in one line), summary (Markdown), links (the event's source, pull requests, issues, messages, documents, deployments, how to test; plus the webhook delivery that started it) and, while it waits for a person, question {text, context, choices: {options, recommended, multiple}}. view: needs_input, in_progress, done, failed or all (default: needs_input when anyone waits, else all); sort: activity (latest first, the default), oldest (waiting longest), progress (furthest along) or created. counts gives how many wait and how many run. next_offset pages.
list_jobsreads
fleet:read
List jobsJobs on every machine, newest first, with status (how the process ended), outcome (whether the task was done), failure kind, the pending question and cost. waiting: true lists only agents waiting for a person. next_before pages.
get_jobreads
fleet:read
Get a jobA job as its page shows it: status, outcome, the agent's response and result excerpt, failure, cost and tokens, the pending question and answer, the progress timeline, the live output when it is being streamed (watch_job), artifacts fetched so far and the commands sent about it.
answer_jobacts, irreversibly
fleet:run
Answer an agentAnswer a job that is waiting for a person (or that ended with outcome needs_human). answer is what the person said; option names the one of the offered options they picked (answer may repeat it), options the several they picked when the question lets a person pick more than one (they reach the agent one per line, before the answer). resume: auto (default) resumes the agent's session with the answer when the run already ended; never only records it. If the machine reports a terminal job missing, the disposition is recorded in the cloud (delivered: cloud_only); the original status, outcome and links remain, and no job resumes.
close_jobacts
fleet:run
Close a waiting jobTake a finished job that waits for a person out of the inbox without answering it: nothing reaches the agent and no session resumes. Use it when the question went stale or the finding cleared by itself (the error stopped, the issue was fixed elsewhere); reason is kept on the job. A job still running is answered with answer_job or stopped with cancel_job instead (not_waiting). Needs skillhook 0.18.0 or later on the machine.
cancel_jobacts, irreversibly
fleet:run
Cancel a jobCancel a queued or running job on its machine. Confirm with the person first.
replay_jobacts, irreversibly
fleet:run
Replay a jobRun a job again with the same payload through the skill as it is now (a new job, trigger replay).
watch_jobacts
fleet:run
Stream a job's outputStream a running job's stdout (or stderr) to the cloud for ttl_seconds (default 900); get_job then shows it as output, refreshed every few seconds.
get_job_artifactreads
fleet:run
Read a job's fileFetch one of a job's files from its machine: stdout or stderr (the agent's transcript), prompt (what it was told), result, response, payload or event (the webhook it got). Up to 256 KiB is returned (the end of stdout and stderr, the start of the others). Secrets are scrubbed on the machine; payload, event and prompt (which contain the webhook body) are withheld when the organisation keeps no bodies.
list_deliveriesreads
fleet:read
List deliveriesWebhooks the machines received, newest first, including rejected, skipped and duplicate ones with the reason. q searches the sender's delivery id, the machine's delivery id, the reason, the code, the path, the address and the user agent (case-insensitive, anywhere); since and until bound when it was received; delivery_id is the sender's id exactly, job the machine's id of the job it started. via: http came to the machine's own URL, ingress through a hosted URL. next_before pages.
get_deliveryreads
fleet:read
Get a deliveryOne webhook delivery: outcome and reason, HTTP status, sender, redacted headers, the job it started and, with include_body, the stored body.
replay_deliveryacts, irreversibly
fleet:run
Replay a deliveryRun a stored delivery again through the skill as it is now. force is needed for deliveries that failed their checks (it skips them); skip_filters ignores the skill's when-filters. machine or skill run it elsewhere: the stored body and redacted headers go to that machine or skill as a fresh run, the way run_skill does (no signature check, no filters, so force and skip_filters do not apply); that needs the body to be stored (no_body otherwise).
list_hosted_urlsreads
fleet:read
List hosted URLsHosted webhook URLs (the cloud receives the webhook and holds it, sealed, up to 72 hours until the machine collects it): per skill whether it is on, its key prefix, what it received and how many deliveries wait for the machine. Never the URL itself: get_hosted_url.
get_hosted_urlreads
fleet:run
Reveal a hosted URLThe hosted URL of a machine's skill, to configure in the webhook sender (GitHub, Sentry, Granola, Stripe…). The machine still checks every delivery's signature with the skill's own secret.
enable_hosted_urlacts, irreversibly
fleet:admin
Turn on a hosted URLCreate a hosted URL for a machine's skill, or a new one: any previous URL for the skill stops working at once (update the sender).
disable_hosted_urlacts, irreversibly
fleet:admin
Turn off a hosted URLTurn a skill's hosted URL off: senders get 404 until it is turned on again, with a new URL. Confirm with the person first.
list_commandsreads
fleet:read
List commandsCommands sent to the machines (by people, keys and the cloud), newest first: type, status, who asked, the ids they were about and their error. get_command has a command's result.
send_commandacts, irreversibly
fleet:read
Send a commandSend any protocol command to a machine and wait (up to 60 s) for its result: ping, health.get {deep, refresh}, runners.get {refresh}, logs.tail {lines}, config.get, config.patch {set, unset}, service.status, service.restart {when: idle|now}, update.check, update.install, schedules.list, schedule.run {name}, schedule.pause {name, reason, until}, schedule.resume {name}, stats.get {since}, secret.list, expose.status, job.list, delivery.list. Needs the scope the command requires (logs, configuration and restarts need fleet:admin); the machine's own policy decides too.
get_commandreads
fleet:read
Get a commandA command's status and result; wait_seconds (up to 30) waits for it to finish.
list_schedulesreads
fleet:read
Schedules and eventsEvery schedule: machine_schedules, the ones machines fire themselves from a repository's skillhook.yaml or a SKILL.md (the repository is their source of truth; paused says whether someone switched one off, by whom, why and until when), and schedules, the Cloud-owned timers, with their recent dispatch events, skips and command results. pause_schedule and resume_schedule switch either kind off and on.
pause_scheduleacts, irreversibly
fleet:run
Pause a scheduleStop a skill's schedule on a machine from firing, without changing its repository: for a schedule from skillhook.yaml or a SKILL.md the machine keeps the pause (its webhook still works, slots that pass are not caught up, a repository pull or restart keeps it, until ends it by itself; needs skillhook 0.16 on the machine); for a Cloud timer it is disabled. reason says why, for whoever looks next. resume_schedule undoes it.
resume_scheduleacts, irreversibly
fleet:run
Resume a scheduleLet a paused schedule fire again from its next slot (slots that passed while paused are not caught up), whether the machine fires it from its repository or it is a Cloud timer.
save_scheduleacts, irreversibly
fleet:admin
Save a Cloud timerCreate or update a named Cloud-owned schedule on a machine. Remove the local schedule before enabling it. Five-field cron and IANA timezone; missed slots and overlapping jobs are skipped. Saving with enabled=false pauses it.
get_settingsreads
fleet:read
Organisation settingsThe organisation (name, slug, plan) and its settings: whether webhook bodies are kept (store_payloads).
update_settingsacts, irreversibly
fleet:admin
Change organisation settingsRename the organisation or change whether the cloud keeps webhook bodies the machines upload (store_payloads: false keeps none from now on).
get_pricingreads
fleet:read
Plans and pricesEvery plan (Free, Pro, Business, Enterprise): its price a month and a year in USD, the limits (machines, people, hosted URLs, hosted deliveries a month, notification channels, API keys, the rate per key, how long webhook bodies are kept), the features, and a checkout_url a person opens to buy it (it signs them in or up first). The same document as GET /api/v1/pricing, which needs no key. Use it to answer what a plan costs or which plan fits.
get_billingreads
fleet:read
Plan and usageThe organisation's plan (code, status, billing period, renews_at, or ends_at when a cancellation is pending), the plan's limits, what the organisation uses of each (machines, people, hosted URLs, hosted deliveries this month, notification channels, API keys) with the room left, the plan the usage fits, what the next plan adds (next_plan, with its checkout_url), and where a person changes the plan. A deployment that does not enforce plans says so (enforced: false).
list_membersreads
fleet:read
List membersThe organisation's people, their roles (viewer, member, admin, owner) and teams (each person's, with member or maintainer), and the teams with their head counts; admin keys also see pending invitations and the teams they join. Inviting, removing, changing roles and team membership are done on the dashboard.
list_channelsreads
fleet:admin
List notification channelsWhere alerts are sent (Slack, webhook, email): which alert types, whether on, and the last delivery or error. Adding a channel is done on the dashboard.
test_channelacts, irreversibly
fleet:admin
Test a notification channelSend a sample alert to a channel and record whether it arrived.
list_audit_logreads
fleet:admin
Audit logEvery change and every command, by whom (person, API key, machine, system), newest first. Payloads, answers and file contents are never in it. action filters by an exact action or a prefix ending in a dot (command., machine., hosted_url.).
list_feedbackreads
fleet:read
Search the feedback boardThe public feedback board shared by every Skillhook organisation: feature requests and published issues with their status (open, planned, in_progress, done, declined, duplicate), votes and comment count. Search before filing (q), then upvote a match instead of filing a duplicate. status defaults to active (open, planned, in progress); all lists every status. viewer.voted says whether this organisation voted. next_cursor pages.
get_feedbackreads
fleet:read
Get a feedback itemOne item of the board by its number (12 or #12) or id: title, description (feature requests), status, votes, the comments (official: true marks the Skillhook team's response) and the timeline of status changes with the team's notes. This organisation's own issues also carry report (its dashboard link, request id and the context it was filed with).
list_my_feedbackreads
fleet:read
My feedback and subscriptionsWhat this organisation filed (feature requests, and issues, which stay private to it and the Skillhook team) and the items it follows because it voted or commented, newest activity first.
request_featureacts, irreversibly
fleet:read
Request a featureAsk for something skillhook or Skillhook Cloud should do, when the person wishes the product did something it does not. Similar requests come back first (created: false, similar): upvote the one that matches with upvote_feedback instead; force: true files anyway. A new request is public on the board with this organisation's vote, and its author is thanked by email and told about every status change.
report_issueacts, irreversibly
fleet:read
Report a problem to SkillhookFile a report with the Skillhook team after a failure, or when something in skillhook or Skillhook Cloud is wrong: say what happened, what you expected and how to reproduce it, name the machine, job or delivery it concerns, and pass request_id (the x-request-id of a failed API call) and context (ids, versions, error codes). Similar open items come back first (created: false, similar): upvote a match with upvote_feedback; force: true files anyway. Reports stay private to this organisation and the team (list_issues, get_feedback), are acknowledged by email (contact_email, else the person who created this API key), routed to the team, and every status change is emailed. Returns its number and dashboard link.
upvote_feedbackacts, irreversibly
fleet:read
Upvote a feedback itemVote for an item on the board as this organisation (one vote per organisation): votes decide what is built and fixed first. The person behind this key is subscribed and thanked by email. Voting twice keeps one vote.
remove_feedback_voteacts, irreversibly
fleet:read
Remove a voteTake this organisation's vote off an item; its people stay subscribed only if they filed it or commented.
comment_on_feedbackacts, irreversibly
fleet:read
Comment on a feedback itemAdd a comment to an item on the board (public on public items; the board shows a first name only). Use it to add a use case or detail to an existing request instead of filing another. 50 a day per organisation.
submit_reviewacts, irreversibly
fleet:run
Post or edit a reviewPost this organisation's public review of Skillhook (one per organisation; posting again edits it, at most once an hour, earlier versions are kept): rating 1-5 and, if the person wants, a title, what they like and dislike, their use case and the name to show. Only post what the person said; never invent a rating. marketing_consent: true only when they agree to be quoted.
list_reviewsreads
fleet:read
Read reviewsPublished reviews of Skillhook with the team's response under each, and the aggregate (count, average, distribution of ratings). mine is this organisation's own review, whatever its status.
list_issuesreads
fleet:read
List problem reportsProblems this organisation reported to the Skillhook team, newest first: number, title, description, kind, severity, status and its item on the feedback board (feedback.number for get_feedback).
get_issuereads
fleet:read
Get a problem reportOne report by number (12 or #12) or id, with its diagnostics and whether its emails went out.

Resource routes

The dashboard's nouns as routes under https://skillhook.dev/api/v1. Where a route and an operation do the same thing the table says which; the operation's input schema (GET /api/v1/tools) documents the body, and the OpenAPI document spells out every parameter.

ToolsScopeWhat
GET /tools
fleet:read
The operation catalogueEvery operation an API key can call, with its JSON Schema, the scope it needs and whether this key has it, plus the instructions written for agents. skillhook's CLI and MCP server build their commands from this.
POST /tools/{tool}
fleet:read
Run one operation of the catalogueThe JSON body is the operation's input (its input_schema in GET /api/v1/tools); the answer is its result. 404 unknown_tool, 403 forbidden for a scope the key lacks, 400 invalid_request for a body that fails the schema. Bodies up to 768 KiB.
AccountScopeWhat
GET /me
fleet:read
Whose key this isThe key's organisation (id, slug, name), its name and scopes, and the role it acts as.
MachinesScopeWhat
GET /machines= list_machines
fleet:read
List machinesEvery paired machine that is not disconnected: status, mode, link state, runners, health summary, versions.
GET /machines/{machine}= get_machine
fleet:read
Get a machineOne machine by id, name or hostname, with its failing checks and its skills.
POST /machines/{machine}/commands= send_command
fleet:read
Send a protocol commandAny protocol command (health.get, logs.tail, config.get, config.patch, service.restart, update.check, …). The key's scope and the machine's own policy decide; 202 while the machine has not answered.
GET /commands/{command}= get_command
fleet:read
Get a commandA command's status and result; ?wait=30 holds the request until it finishes (up to 30 s). Readable with the role that may send it.
SkillsScopeWhat
POST /machines/{machine}/skills/{skill}/run= run_skill
fleet:run
Run a skillRun an installed skill as if a webhook arrived with this payload (no signature check, no filters). wait_seconds waits for the job to finish or to ask a person.
POST /machines/{machine}/secrets
fleet:admin
Generate a skill's secret on the machineThe machine generates the secret and seals it to recipient_key (an X25519 public key the caller made for this request); POST /api/v1/commands/{command}/claim collects the sealed value once. The cloud never holds the value. Needs fleet:admin and a machine in control mode. skillhook cloud secret does all of it.
GET /skills= list_skills
fleet:read
List skillsSkills on every machine, or one machine's (?machine=).
POST /commands/{command}/claim
fleet:admin
Collect a sealed secret onceThe sealed value of a secrets request, to the key that asked, once: 202 {state: pending} until the machine answered, then {state: sealed, sealed}; afterwards claimed, or expired two minutes after the machine received the request; exists when the machine kept the secret it had; failed with the machine's error.
JobsScopeWhat
GET /inbox= list_inbox
fleet:read
The inboxWhat the agents need from a person, what they are doing and what they did: per job its title, state, progress, the result in one line, the summary, typed links (plus the webhook delivery that started it) and, while it waits, its question with choices. Without view: needs_input when anyone waits, else all.
GET /jobs= list_jobs
fleet:read
List jobsNewest first; next_before pages.
GET /jobs/{job}= get_job
fleet:read
Get a jobBy the cloud id or the machine's job id, with its timeline, live output, artifacts and commands.
POST /jobs/{job}/answer= answer_job
fleet:run
Answer an agentDelivered to the waiting run, or the agent's session resumes with the answer when the run already ended (resume: auto). 202 while the machine has not confirmed. With resume: never, a terminal job the machine reports missing gets an audited cloud_only disposition; the command stays failed and the original job outcome is preserved.
POST /jobs/{job}/close= close_job
fleet:run
Close a waiting jobA finished job that waits for a person stops waiting without an answer: nothing reaches the agent and no session resumes. For a question that went stale or a finding that cleared by itself; the job leaves the inbox and its needs_human alert resolves once the machine confirms. 409 not_waiting when it is not waiting or still running; the machine needs skillhook 0.18.0 or later (403 forbidden with the version otherwise). 202 while the machine has not confirmed.
POST /jobs/{job}/cancel= cancel_job
fleet:run
Cancel a jobCancel a queued or running job on its machine.
POST /jobs/{job}/replay= replay_job
fleet:run
Replay a jobRun a job again with the same payload (a new job, trigger replay).
DeliveriesScopeWhat
GET /deliveries= list_deliveries
fleet:read
List deliveriesWebhooks the machines received, newest first, rejected ones included; q searches the sender's delivery id, the machine's id, the reason, code, path, address and user agent; since and until bound received_at; delivery_id and job match exactly. next_before pages.
GET /deliveries/{delivery}= get_delivery
fleet:read
Get a deliveryOne delivery with its redacted headers; ?include=body adds the stored body when the organisation keeps bodies.
POST /deliveries/{delivery}/replay= replay_delivery
fleet:run
Replay a deliveryRun a stored delivery again. force skips the checks it failed; skip_filters ignores the skill's when-filters. With machine or skill, the stored body and redacted headers run on that target as a fresh run (no signature check, no filters); 409 no_body when the body is not stored.
SupportScopeWhat
POST /issues= report_issue
fleet:read
Report a problem to the Skillhook teamAny key may report. 201 with the report and whether the acknowledgement email went out; the same Idempotency-Key (at most 120 characters) from the same key returns the original with 200. 10 an hour per key, 30 per organisation.
GET /issues= list_issues
fleet:read
List problem reportsThe organisation's reports, newest first; next_before pages. Statuses are the board's (acknowledged, resolved and closed still filter, as planned, done and declined).
GET /issues/{issue}= get_issue
fleet:read
Get a problem reportBy number (12 or #12) or id, with its diagnostics and whether its emails went out.
FeedbackScopeWhat
GET /feedback= list_feedback
no key
The feedback boardFeature requests and published issues of every organisation: status, votes, comment count, author (a first name). status: active (open, planned, in progress; the default), one status, or all; sort: top, new or recent_activity; q searches titles and descriptions. With a key, viewer.voted says whether the organisation voted; mine=true (key required) lists what the organisation filed and follows instead ({items, subscriptions}). next_cursor pages.
GET /feedback/{item}= get_feedback
no key
Get a feedback itemBy its number (12 or #12) or id: the item, its comments (official marks the team's responses) and its timeline. A private issue answers only its own organisation's keys, with report {number, request_id, context, dashboard_url}.
POST /feedback/features= request_feature
fleet:read
Request a featureSimilar requests come back first (200 {created: false, similar, hint}): upvote a match instead. force: true files anyway (201 {created: true, item}). Public on the board with the organisation's vote; the author is thanked and told about every status change by email. 10 items a day per organisation.
POST /feedback/issues= report_issue
fleet:read
Report an issueAn issue for the Skillhook team, private to the organisation and staff (staff may publish a sanitised title). request_id is the x-request-id of the failed call; context is any JSON the report is about (versions, error code, ids), never public. Similar open items come back first (200 {created: false, similar}); force: true files anyway (201 {created: true, issue, item}).
POST /feedback/{item}/votes= upvote_feedback
fleet:read
Upvote an itemThe organisation's vote (one per organisation; again keeps one). Subscribes the person behind the key, thanked by email at most once a day. 409 closed for a done, declined or duplicate item.
DELETE /feedback/{item}/votes= remove_feedback_vote
fleet:read
Remove a voteTakes the organisation's vote back.
POST /feedback/{item}/comments= comment_on_feedback
fleet:read
Comment on an itemAs the organisation (the board shows a first name). 50 a day per organisation.
GET /reviews= list_reviews
no key
ReviewsPublished reviews with our response under each, and the aggregate {count, average, distribution}; sort new (default) or top. With a key, mine is the organisation's own review.
GET /reviews/me
fleet:read
The organisation's reviewWhatever its status (published, pending a check, hidden), or null.
PUT /reviews/me= submit_review
fleet:run
Post or edit the organisation's reviewOne per organisation; an edit (at most one an hour) keeps the earlier version. rating 1-5, optional title, body, likes, dislikes, use_case, display_name (default: a first name), display_company, marketing_consent. Published at once unless the automated checks hold it for staff (status pending).
BillingScopeWhat
GET /pricing
no key
The plansEvery plan in the shared pricing shape of Meter's products: product, currency, updated_at, plans[] {id, name, price {monthly, yearly} in dollars, included, limits, features, overage, trial, checkout_url} (with the older code, monthly_cents and yearly_cents), add_ons, free_tier, how_to_buy and docs, and whether this deployment enforces the limits. A checkout_url signs a person in (or up) and goes to Stripe Checkout; ?ref= names who sent them (agent-api by default). The catalogue operation get_pricing answers the same with a key.
GET /billing= get_billing
fleet:read
The organisation's plan and usageThe plan in force with renews_at (or ends_at when a cancellation is pending), its limits, what the organisation uses of each with the room left, the plan the usage fits, what the next plan adds (next_plan) and where a person changes the plan.
POST /billing/checkout
no key
A link to buy a planWith an admin key (fleet:admin), a Stripe Checkout link for the key's organisation that expires in 24 hours (kind: checkout), or the Billing page when it already pays (kind: dashboard): create_checkout_link does the same. Without a key, the plan's checkout_url (kind: signup), which signs a person in or up first. Charges nothing; a person pays in the browser.
POST /billing/portal= get_billing_link
fleet:admin
A link to invoices and the cardStripe's Customer Portal for the organisation (kind: portal): invoices, receipts, the card and billing details; the Billing page when it never paid (kind: dashboard). Plan changes and cancelling stay on the Billing page.

POST /api/mcp: Streamable HTTP, stateless: one JSON-RPC request per POST (initialize, tools/list, tools/call). The tools are the catalogue's operations this key's scope allows; a tool's error is a tool result with isError and structuredContent.error {code, status, message, retryable, retry_after_seconds?, request_id, details?} (the codes of the problems below; details holds the problem's other fields, such as reason), never a JSON-RPC error. GET answers 405, DELETE 200 (no sessions). MCP and plugins says how to connect.

Errors

Every failure is RFC 9457 application/problem+json: type links to the code's entry below, title and detail say what happened, code is for programs and request_id for support. A failure on our side that a retry may fix is 503 unavailable with Retry-After, never a 401 or a 404.

CodeStatusMeaning
unauthorized401No credential: send an organisation API key as Authorization: Bearer shc_….
invalid_key401The key is unknown, revoked or expired. Create a new one under Settings → API keys.
forbidden403The key's scope does not allow this operation, or the role behind it cannot send that command.
invalid_request400The body or a parameter failed validation; the detail names the field.
invalid_json400The body is not JSON.
invalid_args400A command's arguments do not match the protocol (send_command, run_skill…), or save_schedule cannot make that timer; then `reason` (over MCP structuredContent.error.details.reason) names the check: invalid_cron, invalid_timezone, no_occurrence, payload_too_large, skill_not_served or skill_disabled.
unknown_command400No such protocol command type, or (404) no such command id in this organisation.
unknown_tool404No operation of that name; GET /api/v1/tools lists them.
unknown_machine404No machine with that id, name or hostname in this organisation.
unknown_job404No job with that cloud id or machine job id in this organisation. For the id of a command that starts a job (run_skill, replay) whose job has not reached the cloud yet, it carries command_id, command_status and job_local_id, with Retry-After while one is still expected.
unknown_delivery404No delivery with that id in this organisation.
unknown_alert404No open alert with that id.
unknown_channel404No notification channel with that id.
unknown_issue404No problem report with that number or id.
no_hosted_url404The skill has no hosted URL turned on; enable_hosted_url makes one.
not_found404The machine, job, delivery or invitation named does not exist in this organisation.
ambiguous_machine409More than one machine has that name; use its id.
ambiguous_job409More than one job has that machine job id; use the cloud id.
ambiguous_delivery409More than one delivery has that machine delivery id; use the cloud id.
not_waiting409close_job: the job is not waiting for a person (answered, resumed or closed already), or it is still running: answer its question or cancel it.
revoked409The machine was disconnected; pair it again to send it commands.
denied_by_machine409The machine's mode or its allow/deny lists refuse this command; the detail says which.
no_body409The delivery's whole body is not stored here (the organisation keeps no webhook bodies, the machine keeps them home, the plan's retention window passed, or it was too large or binary), so it cannot run on another machine or skill. Replay it where it arrived instead.
plan_limit402The organisation's plan has no room for one more of what was asked (a machine, a person, a hosted URL, a key); the detail names the limit. The body also says limit, plan, used, max, upgrade {plan, name, limit, checkout_url} (the plan that lifts it and the link a person opens to buy it), pricing (every plan in one line) and pricing_url; an MCP tool error carries the same as details. Upgrade, or make room.
billing_unavailable409Plans are not sold on this deployment, or the plan cannot be sold here (no Stripe price, an Enterprise agreement).
too_large413The body is over the limit (512 KiB; 768 KiB for a whole SKILL.md and on /api/mcp).
closed409The feedback item is done, declined or a duplicate: it takes no more votes (vote for the item a duplicate joined).
rate_limited429Over the limit: 600 requests a minute per key, 10 problem reports an hour per key, 10 feedback items and 50 comments a day and one review edit an hour per organisation, 5 channel tests a minute per channel. Wait Retry-After seconds.
internal500Something went wrong on our side; quote the request_id when you report it.
unavailable503The service could not reach its database; retry after Retry-After seconds. Never a judgement on your key.