API reference

Build hardened server images from a spec you write, check how each image was built, and install it on your own servers.

The API is plain HTTPS with JSON in and JSON out. Every operation in this reference is also an MCP tool with the same name, and the dashboard uses the same operations. The machine-readable description of the whole API is at GET /v1.

Base URL

https://api.tarsana.io

Every path starts with /v1. Send JSON request bodies with Content-Type: application/json.

Authentication

Send exactly one credential with every request that needs one:

Requests that read or change something in your tenant also send your tenant ID in the X-Tarsana-Tenant header, and the same ID in the address. Tarsana checks that your credential belongs to that tenant.

curl "https://api.tarsana.io/v1/tenants/acme/audit" \
  -H "X-Tarsana-Access-Token: $ACCESS_TOKEN" \
  -H "X-Tarsana-Tenant: acme"

A request with no credential, or one Tarsana does not recognise, gets unauthenticated. A credential whose role does not allow the operation gets forbidden, with the roles that do. Each operation's page says which roles can call it:

Signing up, signing in and reading the API description need no credential.

Errors

A request to the API that Tarsana refuses, including one whose body is not valid JSON, gets an HTTP status of 400 or higher and an error object with a code, a message for people, sometimes a detail object, and a doc_url that links to the code's entry in the error reference:

{
  "error": {
    "code": "rate_limited",
    "message": "One sentence that says what went wrong.",
    "detail": {"retry_after_seconds": 30},
    "doc_url": "https://docs.tarsana.io/api/errors#rate_limited"
  }
}

Act on the code, never on the message. The error reference lists every code with what happened and what to do.

Retries and idempotency

You can repeat these requests safely:

Every operation with the Read badge changes nothing and can be repeated at any time.

Rate limits

When you send too many requests in a short time you get rate_limited with HTTP status 429. The Retry-After header and detail.retry_after_seconds say how many seconds to wait.

Request IDs

Answers do not carry a request ID yet. If you contact Tarsana support about a request, include the time you sent it, the operation, your tenant ID and the error code.

Operations

Create your account

Sign up, then sign in.

Set up access

Create API access tokens for your scripts and MCP clients, and store the API token of your cloud provider.

Build an image

Check your spec, submit it, follow the build and verify what it produced.

Run it on your servers

Create a server from your spec or install your image on one, review the servers in your cloud account, and remove the ones you no longer need.

Reference

The machine-readable description of this API.

View this page as Markdown