Skip to content

apistockdocs

v0.4 GitHub apistock.dev

API reference/Overview

API reference

This is the API of the example multi-tenant app in examples/full-multi, rendered from its checked-in openapi.json. Every app you create with aps new serves the same reference for its own API at /docs, and aps dev serves the API at http://127.0.0.1:8080.

Base URL#

Send requests to the server the API runs on. "Try it" on each endpoint asks for its address.

Authentication#

bearer. Session token from POST /v1/auth/login with "transport": "bearer". Browsers use the session cookie that login sets instead.

Errors#

Errors are application/problem+json. Match on code: it stays the same, while messages may change.

codestringrequired

Stable machine-readable error code

statusintegerrequired

HTTP status code

format: int64

titlestringrequired

Short summary of the problem type

detailstring

Human-readable explanation

errorsarray of object

Field-level validation errors

nullable

2 fields

messagestringrequired

What is wrong

locationstring

Where the error occurred

request_idstring

Correlates with server logs and traces

typestring

URI identifying the problem type

Endpoints#

Ops: audit

GET/ops/auditList audit events, newest first GET/ops/audit/{id}Get an audit event

Ops: auth

GET/ops/auth/providersList sign-in methods and what they need

Ops: job definitions

GET/ops/jobs/definitionsList job definitions GET/ops/jobs/definitions/{name}Get a job definition PUT/ops/jobs/definitions/{name}Change a job's configuration DEL/ops/jobs/definitions/{name}Reset a job to its code defaults GET/ops/jobs/definitions/{name}/historyList a job definition's changes POST/ops/jobs/definitions/{name}/runRun a job now GET/ops/jobs/scheduledList enabled scheduled jobs, soonest first

Ops: job runs

GET/ops/jobs/runsList job runs, newest first GET/ops/jobs/runs/{id}Get a job run POST/ops/jobs/runs/{id}/cancelCancel a job run POST/ops/jobs/runs/{id}/retryRetry a job run now

Ops: email

GET/ops/mailShow how the app sends email POST/ops/mail/testSend a test email

Ops: job queues

GET/ops/queuesList active job queues POST/ops/queues/{name}/pausePause a queue on every instance POST/ops/queues/{name}/resumeResume a paused queue

Ops: releases

GET/ops/releasesList releases, newest first GET/ops/releases/currentList the releases running now GET/ops/releases/instancesList instance starts, newest first

Ops: settings

GET/ops/settingsList runtime settings GET/ops/settings/{key}Get a runtime setting PUT/ops/settings/{key}Change a runtime setting DEL/ops/settings/{key}Reset a runtime setting to its default GET/ops/settings/{key}/historyList a runtime setting's changes

Auth

POST/v1/auth/apple/callbackApple's return to the API POST/v1/auth/apple/notificationsApple's server-to-server notifications POST/v1/auth/apple/tokenSign in with an Apple ID token GET/v1/auth/google/callbackGoogle's return to the API POST/v1/auth/google/tokenSign in with a Google ID token GET/v1/auth/identitiesList linked Google and Apple accounts DEL/v1/auth/identities/{id}Unlink a Google or Apple account POST/v1/auth/loginSign in POST/v1/auth/login/mfaFinish signing in with a second factor POST/v1/auth/login/mfa/passkeyStart a passkey second factor POST/v1/auth/logoutSign out this device POST/v1/auth/logout-allSign out every device GET/v1/auth/meGet the signed-in user DEL/v1/auth/meDelete the account POST/v1/auth/mfa/recovery-codesReplace the recovery codes POST/v1/auth/mfa/totpStart setting up an authenticator app DEL/v1/auth/mfa/totpTurn off the authenticator app POST/v1/auth/mfa/totp/confirmTurn on the authenticator app GET/v1/auth/passkeysList passkeys POST/v1/auth/passkeysAdd a passkey POST/v1/auth/passkeys/loginSign in with a passkey POST/v1/auth/passkeys/login/optionsStart signing in with a passkey POST/v1/auth/passkeys/registrationStart adding a passkey POST/v1/auth/passkeys/verificationConfirm a change with a passkey PATCH/v1/auth/passkeys/{id}Rename a passkey DEL/v1/auth/passkeys/{id}Remove a passkey PUT/v1/auth/passwordChange the password POST/v1/auth/password/forgotEmail a password reset code POST/v1/auth/password/resetSet a new password with a reset code POST/v1/auth/registerCreate an account GET/v1/auth/sessionsList signed-in devices DEL/v1/auth/sessions/{id}Sign out one device POST/v1/auth/verify-emailVerify an email address with its code POST/v1/auth/verify-email/resendSend a new verification code POST/v1/auth/{provider}/nonceGet a nonce for a native sign-in GET/v1/auth/{provider}/startSign in with Google or Apple in a browser

Example

POST/v1/echoEcho a message GET/v1/pingCheck the API is reachable

Organisations

POST/v1/invitations/acceptAccept an invitation GET/v1/orgsList your organisations POST/v1/orgsCreate an organisation GET/v1/orgs/{orgId}Get an organisation PATCH/v1/orgs/{orgId}Rename an organisation DEL/v1/orgs/{orgId}Delete an organisation GET/v1/orgs/{orgId}/invitationsList open invitations POST/v1/orgs/{orgId}/invitationsInvite someone DEL/v1/orgs/{orgId}/invitations/{invitationId}Revoke an invitation POST/v1/orgs/{orgId}/invitations/{invitationId}/resendResend an invitation POST/v1/orgs/{orgId}/leaveLeave an organisation GET/v1/orgs/{orgId}/membersList members PATCH/v1/orgs/{orgId}/members/{userId}Change a member's role DEL/v1/orgs/{orgId}/members/{userId}Remove a member POST/v1/orgs/{orgId}/restoreRestore a deleted organisation

Projects

GET/v1/orgs/{orgId}/projectsList the organisation's projects POST/v1/orgs/{orgId}/projectsCreate a project GET/v1/orgs/{orgId}/projects/{id}Get a project PATCH/v1/orgs/{orgId}/projects/{id}Update a project DEL/v1/orgs/{orgId}/projects/{id}Delete a project

System

GET/versionBuild information

Was this page useful?

v0.4