Developers

Four requests cover the normal integration.

Your backend starts a run, follows it, and reads the result, with a key that can do only what you allowed. No SDK required: it is HTTPS and JSON.

Read the API guide Download openapi.json

$run = Http::withToken(config('services.vendor.key'))
    ->withHeaders(['Idempotency-Key' => $ticket->uuid])
    ->post('https://vendor.sh/api/v1/workflows/inbound-email/runs', [
        'input' => ['subject' => $ticket->subject],
    ])->throw()->json();

// 202 Accepted → $run['data']['status'] === 'pending'

const run = await fetch(
  "https://vendor.sh/api/v1/workflows/inbound-email/runs",
  { method: "POST",
    headers: { Authorization: `Bearer ${token}`,
               "Idempotency-Key": ticket.uuid },
    body: JSON.stringify({ input: { subject: ticket.subject } }) },
).then((r) => r.json());

// 202 Accepted → run.data.status === "pending"

run = httpx.post(
    "https://vendor.sh/api/v1/workflows/inbound-email/runs",
    headers={"Authorization": f"Bearer {token}",
             "Idempotency-Key": ticket.uuid},
    json={"input": {"subject": ticket.subject}},
).raise_for_status().json()

# 202 Accepted → run["data"]["status"] == "pending"

$ curl -X POST https://vendor.sh/api/v1/workflows/inbound-email/runs \
    -H "Authorization: Bearer $VENDOR_TOKEN" \
    -H "Idempotency-Key: $TICKET_UUID" \
    -d '{"input": {"subject": "Refund for #4471"}}'

The normal path

Start it, follow it, read it, and know what you are calling.

Exact paths and schemas: /openapi.json

01 POST Start a run /api/v1/workflows/{deployment}/runs Send the input and an Idempotency-Key. Answers 202 with a queued run, or 200 when it finishes inline.
02 GET Read a run /api/v1/runs/{run} The current status, the output, usage and cost. Poll it until the status is final.
03 GET Build a safe form /api/v1/workflows/{deployment}/schema The live input rules, so your application can validate before it sends.
04 GET Explore the contract /openapi.json Every path, parameter and schema in OpenAPI 3.1. Generate a client from it.

Limited service keys

A leaked key should be a small problem, and a short one.

Each project service key belongs to one project, carries only the abilities you tick, may call only the deployments you list, and stops working at its expiry or the moment you revoke it.

A new secret is shown once, and never again.
A key is limited to selected abilities and deployments.
An Idempotency-Key stops the same request running twice.
Generated client files carry no secret.

billing-backend ····3f9a

Illustrative

Project: Acme Support
Abilities: runs:create runs:read
Deployments: inbound-email · production
Expires: in 105 days
Last used: 2 minutes ago

Reference

The exact API lives in one contract.

Start with the API guide or a generated server client.

Use Laravel, PHP, TypeScript, Python, or any backend that can send an HTTP request.

Read the API guide Talk to us

No card required · Cancel anytime