---
title: "External API"
description: "Authentication, conventions, and the complete SDK-facing HTTP reference."
category: "Reference"
---

Use the external API to submit and inspect workflows, operate schedules, or implement a custom worker. For .NET and Java applications, start with their SDK guides; the SDK owns worker sessions, leases, acknowledgements, and result retries.

## API address

The default local address is `http://localhost:8081`. The dashboard's `/api` endpoints are a separate, cookie-authenticated interface and are not interchangeable with this contract.

[Download the OpenAPI specification](/openapi.yaml). It contains 25 paths, including operation definitions and request/response schemas.

## Authentication

Use an application API key in `X-API-Key` for producer operations. Treat it as a secret. It scopes requests to an application; it is not a dashboard user's role.

Worker sessions are returned at bootstrap. Follow the operation-specific security requirements rather than assuming every route uses the same headers. See [HTTP worker authentication](/docs/http-workers) for the exact lifecycle.

Never put a key in a query string or paste it into a shared log. The legacy create route accepts its key in the request body and creates a new pipeline on each call. Prefer the idempotent create contract for new integrations.

## Choose a reference

| Reference | Operations |
| --- | --- |
| [Pipeline API](/docs/api/pipelines) | Create, lookup, inspect, cancel, append, approve, logs, version |
| [Schedule API](/docs/api/schedules) | Register, update, list, inspect history, pause, resume, archive, trigger |
| [Worker API](/docs/api/workers) | Bootstrap, heartbeat, shutdown, pull, lease, result, acknowledgement |
| [Schemas](/docs/api/schemas) | Complete fields, required values, limits, enums, and nested structures |

## Retry an unknown creation outcome

Use `POST /pipelines/idempotent` with a stable application-scoped key and the same creation intent. Repeating an equivalent request returns the existing pipeline. Reusing the key for a different intent returns 409. Do not respond to a timeout by falling back to the legacy create route.

Creation idempotency does not deduplicate external side effects inside handlers. See [reliable execution](/docs/reliability).

## Interpret responses

A 400 usually indicates a contract or validation error. Check the request against its schema. A 401 indicates rejected credentials or session requirements. A 409 indicates a conflicting state or idempotency intent. Read the operation's response table before retrying.

For stage results, 202 means broker-confirmed acceptance; the result consumer applies state asynchronously. Retry a transient 503 and acknowledge the delivery only after acceptance. Poll the pipeline or inspect the dashboard for its eventual state.

## Limits and compatibility

Accepted fields may exist for compatibility without providing an active runtime feature. The schema descriptions and [policy guide](/docs/policies) identify important limits. Use supported SDKs for normal workers and test a custom transport against a real local server. These docs follow the 0.5.0 source contract.