Shipfox exposes an HTTP API that the dashboard uses and that you can call directly to
automate projects, definitions, runs, and runners. This page covers the endpoints
meant for user automation. Endpoints that runners and provisioners use to execute
jobs are a separate machine protocol — see Internal protocols.
Base URL
The API is served at the root path — there is no version prefix.
- Managed:
https://api.shipfox.io
- Local / self-hosted:
http://localhost:16101 by default (the port is
configurable).
Authentication
User endpoints authenticate with a bearer token. Obtain one by signing in, then
send it in the Authorization header.
# Sign in
curl -X POST https://api.shipfox.io/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "password": "…"}'
# → { "token": "<JWT>", "user": {…}, "membership": {…} }
# Call an authenticated endpoint
curl https://api.shipfox.io/workspaces \
-H "Authorization: Bearer <JWT>"
POST /auth/refresh issues a new one from the
HttpOnly refresh cookie set at login (a browser flow). Runner registration tokens,
job lease tokens, and provisioner tokens are not general API credentials — they
belong to the internal protocols below.
Endpoints
The tables list the primary endpoints per resource; obvious CRUD sub-routes are
omitted. All require Authorization: Bearer <JWT> unless the Auth column says
otherwise.
Auth & session
| Method | Path | Purpose | Auth |
|---|
| POST | /auth/signup | Create an account | None |
| POST | /auth/login | Sign in; returns an access token | None |
| POST | /auth/refresh | Refresh the access token | Cookie |
| POST | /auth/logout | Sign out | User |
| GET | /auth/me | Current signed-in user | User |
| POST | /auth/password/reset | Request a password reset | None |
Workspaces
| Method | Path | Purpose |
|---|
| GET | /workspaces | List your workspace memberships |
| POST | /workspaces | Create a workspace |
| GET | /workspaces/{workspaceId}/members | List members |
| POST | /workspaces/{workspaceId}/invitations | Invite a member |
Projects
| Method | Path | Purpose |
|---|
| POST | /projects | Create a project bound to a repository |
| GET | /projects | List projects (workspace_id, pagination, search) |
| GET | /projects/{projectId} | Get a project |
Workflow definitions
| Method | Path | Purpose |
|---|
| POST | /definitions | Create or update a definition from YAML |
| GET | /definitions | List definitions (workspace_id, project_id) |
| GET | /definitions/{definitionId} | Get a definition |
| POST | /definitions/validate | Validate workflow YAML without saving |
Workflow runs
| Method | Path | Purpose |
|---|
| POST | /workflow-definitions/{definitionId}/fire-manual | Fire a manual trigger |
| GET | /workflows/runs | List runs (project_id, status, definition_id, …) |
| GET | /workflows/runs/{id} | Run detail with jobs and steps |
| POST | /workflows/runs/{id}/cancel | Cancel a run |
| POST | /workflows/runs/{id}/rerun | Rerun a run |
| GET | /steps/{stepId}/attempts/{attempt}/logs | Read a page of step logs |
Runners & provisioners
| Method | Path | Purpose |
|---|
| POST | /workspaces/{workspaceId}/runners/manual-registration-tokens | Create a manual registration token |
| GET | /workspaces/{workspaceId}/runners/active | List active runners |
| POST | /workspaces/{workspaceId}/provisioners/tokens | Create a provisioner token |
| GET | /workspaces/{workspaceId}/provisioners/active | List active provisioners |
Agent providers
| Method | Path | Purpose |
|---|
| GET | /agent/provider-catalog | List available providers and models |
| GET | /workspaces/{workspaceId}/agent | List configured providers |
| PUT | /workspaces/{workspaceId}/agent | Configure a provider |
| POST | /workspaces/{workspaceId}/agent/{providerId}/default | Set the default provider |
Integrations & trigger events
| Method | Path | Purpose |
|---|
| GET | /integration-connections | List connections (workspace_id) |
| GET | /integration-providers | List available integration providers |
| POST | /integrations/github/install | Start a GitHub App installation |
| GET | /trigger-events | List received trigger events (audit log) |
| GET | /trigger-events/{eventId} | Get one trigger event |
Webhook ingest endpoints
These are provider callbacks, not user API endpoints — external providers POST
to them with a signature. See Integrations.
| Method | Path | Provider |
|---|
| POST | /webhooks/integrations/github | GitHub (X-Hub-Signature-256) |
| POST | /webhooks/integrations/sentry | Sentry (signed) |
| POST | /webhook/{connectionId} | Custom webhook |
Errors
Errors return a JSON body with a stable code, optional client-safe details, and
an appropriate HTTP status:
{ "code": "project-already-exists", "details": { "existing_project_id": "…" } }
validation-error (400), unauthorized (401), forbidden
(403), not-found (404), and resource conflicts like project-already-exists
(409). Schema-validation failures use validation-error with a message naming the
offending field.
Internal protocols
Runners and provisioners authenticate with their own tokens (runner registration
sf_mrt_/sf_ert_, runner session, job lease, provisioner sf_pt_) against a
separate set of endpoints — claiming jobs, fetching steps, reporting results,
appending logs, and polling for demand. These are an internal machine protocol, not
part of the user API; don’t call them directly. See
Runners and Runner provisioners. 
