# Get the full API description as JSON {#top}

**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

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

## Example response

```json
{
  "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

| Code | HTTP | What it means |
|---|---|---|
| [`rate_limited`](/api/errors#rate_limited) | 429 | You sent too many requests in a short time. Wait for the number of seconds in `retry_after_seconds`, then try again. |
| [`surface_fault`](/api/errors#surface_fault) | 500 | Something went wrong on our side. Try again later, and contact Tarsana support if it keeps happening. |