Get the full API description as JSON

Read · GET /v1 · MCP tool describe

Returns this API's machine-readable description: every operation, field and error code. Use it to generate a client or to see what the API offers. You do not need to sign in.

You do not need to sign in.

Parameters

This operation takes no parameters.

Returns

A JSON object with these keys: schema, api_version, title, summary, boundary, operation_kinds, roles, admission_gates, errors, refusal, retention, build_runtime, steps, signup, operations, guarantee, caller_authenticated.

Example request

curl https://api.tarsana.io/v1

Example response

{
  "schema": "tarsana.selfservice-api/v1",
  "api_version": "v1",
  "title": "Tarsana self-service API",
  "summary": "Build hardened server images from a spec you write, check how each image was built, and install it on your own servers.",
  "boundary": {
    "guarantee": "namespaces are separated, callers are not authenticated",
    "caller_authenticated": false,
    "statements": []
  },
  "operation_kinds": [
    {
      "id": "read",
      "badge": "Read",
      "summary": "Reads information and changes nothing.",
      "mutates": false,
      "runs_admission_gates": false
    }
  ],
  "roles": [
    {
      "id": "viewer",
      "audience": "tenant",
      "scopes": [
        "read"
      ],
      "summary": "Can read your submissions and download what your builds produced."
    }
  ],
  "admission_gates": [
    {
      "id": "spec_schema",
      "status": "wired",
      "refusal_code": "spec_invalid"
    }
  ],
  "errors": [
    {
      "code": "no_such_submission",
      "http_status": 404,
      "exit_code": 1,
      "meaning": "You have no submission with this ID. Check the ID that `submit` returned."
    }
  ],
  "refusal": {
    "envelope": {
      "name": "error"
    },
    "fields": [
      {
        "role": "code",
        "name": "code",
        "required": true
      }
    ],
    "doc_url": "https://docs.tarsana.io/api/errors#{code}"
  },
  "retention": {
    "operation": "status",
    "field": "retained_tooling",
    "artifact": "retained-tooling"
  },
  "build_runtime": {},
  "steps": [
    {
      "id": "build",
      "title": "Build an image",
      "operations": [
        "validate",
        "submit",
        "status"
      ]
    }
  ],
  "signup": {
    "begin": "signup",
    "complete": "complete-signup",
    "role": "deployer",
    "link_ttl_seconds": 900
  },
  "operations": [
    {
      "id": "submit",
      "summary": "Submit a spec to build an image",
      "http": {
        "method": "POST",
        "path": "/v1/tenants/{tenant}/specs"
      }
    }
  ],
  "guarantee": "namespaces are separated, callers are not authenticated",
  "caller_authenticated": false
}

Errors

View this page as Markdown