Submit a spec to build an image

Change · POST /v1/tenants/{tenant}/specs · MCP tool submit

Checks your spec, stores it and starts a build. You get back a submission ID, which is the spec's hash. Submitting the same spec again returns the same submission instead of starting a second build, and created tells you whether this call stored it. To check a spec without building it, use validate.

Roles that can call it: builder, deployer.

Parameters

Name	In	Required	Description
`tenant`	path	yes	Your tenant ID
request body	body	yes	Your image spec, as JSON (on the command line, a YAML or JSON file)

Returns

A JSON object with these keys: submission, tenant, spec_hash, state, created, gates, pipeline, guarantee, caller_authenticated, provisioning.

Example request

curl -X POST https://api.tarsana.io/v1/tenants/acme/specs \
  -H "X-Tarsana-Access-Token: $ACCESS_TOKEN" \
  -H 'X-Tarsana-Tenant: acme' \
  -H "Content-Type: application/json" \
  --data @spec.json

Example response

{
  "submission": "sha256:cdff062988d4722b2ff052c97ebefb8b571858c493ce47b159df73b1c88809b1",
  "tenant": "acme",
  "spec_hash": "sha256:cdff062988d4722b2ff052c97ebefb8b571858c493ce47b159df73b1c88809b1",
  "state": "accepted",
  "created": true,
  "gates": [
    {
      "gate": "tenant_name",
      "verdict": "pass",
      "status": "wired",
      "detail": "A sentence about this check.",
      "report": null
    },
    {
      "gate": "spec_schema",
      "verdict": "pass",
      "status": "wired",
      "detail": "A sentence about this check.",
      "report": null
    },
    {
      "gate": "policy_precheck",
      "verdict": "pass",
      "status": "wired",
      "detail": "A sentence about this check.",
      "report": {
        "violations": [],
        "warnings": []
      }
    }
  ],
  "pipeline": {
    "job": "j-bbdde9adc372c296",
    "state": "dispatched",
    "created": true,
    "what": "A sentence about the build's progress."
  },
  "guarantee": "namespaces are separated, callers are not authenticated",
  "caller_authenticated": false,
  "provisioning": {
    "state": "not_requested",
    "provider": null,
    "target": null,
    "mechanism": null,
    "attested": null,
    "correlation_id": null,
    "what": "A sentence about the installation."
  }
}

Errors

Code	HTTP	What it means
`invalid_parameter`	400	A value in your request does not have the expected format, for example a submission ID that is not a spec hash. Check the value against the field's description and try again.
`tenant_refused`	400	This tenant ID is not allowed, or is not in the expected format. Use a different ID made of lower-case letters, digits, dots, dashes and underscores.
`spec_invalid`	400	Your spec does not match the spec format. Fix each problem listed in the response, at the path it gives, and send the spec again.
`spec_unreadable`	400	The request has no spec, or the spec could not be parsed. Send the spec as valid JSON, or as a YAML or JSON file on the command line.
`policy_denied`	400	Your spec breaks one or more rules of the security policy. Change your spec to meet each rule listed in the response, then submit it again.
`no_acting_tenant`	400	Your request does not say which tenant you are acting for. Send your tenant ID in the `X-Tarsana-Tenant` header, or with `--as` on the command line.
`isolation_refused`	403	This address belongs to a tenant ID you do not have access to. Check the tenant ID in the address and in your request header.
`policy_unavailable`	503	Your spec could not be checked against the security policy, so it was not accepted. This is a problem on our side: try again later, or contact Tarsana support.
`dispatch_failed`	502	Your submission was stored, but its build could not be started. Submit the same spec again to start it; if your tenant is over a quota, you get `quota_exceeded` instead.
`quota_exceeded`	429	Your submission was stored, but no build was started because your tenant is over a quota. The response shows each limit and your usage; submit again when you are back under the limit.
`unauthenticated`	401	Your request has no credential, or one that Tarsana does not recognise. Sign in with `login`, or send a valid access token.
`forbidden`	403	Your role does not allow this operation. The response names the roles that do; ask for a credential with one of them.
`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`	500	Something went wrong on our side. Try again later, and contact Tarsana support if it keeps happening.

View this page as Markdown