API access

Start your automations from your own code, or from Claude Desktop and Cursor.

Getting a key

Automations → API → Create API key. The key is shown once and never again — copy it then. Only a hash is stored, so a leaked database row cannot be replayed as a credential.

Send it as Authorization: Bearer vln_… or as an X-Api-Key header.

Never put a key in front-end code. Anyone who opens the page can read it.

The endpoints

# Everything on the account
curl https://volnyn.com/api/v1/automations \
  -H "Authorization: Bearer vln_your_key"

# One automation, with its ten most recent runs
curl https://volnyn.com/api/v1/automations/123 \
  -H "Authorization: Bearer vln_your_key"

# Start one — any JSON body reaches the run as material to work on
curl -X POST https://volnyn.com/api/v1/automations/123/run \
  -H "Authorization: Bearer vln_your_key" \
  -H "Content-Type: application/json" \
  -d '{"customer":"Acme","amount":499}'

# Recent runs
curl https://volnyn.com/api/v1/runs?limit=25 \
  -H "Authorization: Bearer vln_your_key"

# One run's outcome, including its output once finished
curl https://volnyn.com/api/v1/runs/456 \
  -H "Authorization: Bearer vln_your_key"

Runs are queued. An automation drives a full agentic loop and can take minutes, so starting one returns before it finishes. Poll the run for its result.

Rate limit: 60 requests per minute per key.

SDKs

Thin Python and JavaScript clients live in sdk/ in the repository. Both are small on purpose — the README shows the equivalent curl for every call, because a client you cannot see through is one you cannot debug.

from volnyn import Volnyn

v = Volnyn("vln_your_key")
run = v.run(123, {"customer": "Acme"})
print(v.wait(run["id"])["status"])

import { Volnyn } from './volnyn.js';

const v = new Volnyn('vln_your_key');
const run = await v.run(123, { customer: 'Acme' });
console.log((await v.wait(run.id)).status);

Both wait helpers raise on timeout rather than returning a half-finished run, so "still going" cannot be mistaken for "produced nothing".

MCP — from Claude Desktop or Cursor

Your automations and skills can appear as tools inside any assistant that speaks MCP.

{
  "mcpServers": {
    "volnyn": {
      "url": "https://volnyn.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer vln_your_key" }
    }
  }
}

They show up as automation_<id> and skill_<slug>.

Skills run inline and return their result, because that is what the caller asked for and can use. Automations are queued and answer with a run id — one can take minutes and carries real side effects, and a client holding a socket open for that is a client that times out.