Skip to main content

Contracts API

The archetypes endpoints let you list available contract templates and generate a populated devcontract.json. These are the endpoints called by the ticketyboo-gate VS Code extension's Brief Wizard. They use a /v1/ path prefix and require an API key.

Authentication

Both endpoints require an API key sent as the x-api-key header. Keys are generated from your account page and begin with tbo-.

x-api-key: tbo-your-key-here

GET /v1/archetypes

GET /v1/archetypes API key required

Returns the list of available contract archetypes. Each archetype represents a pre-built contract template for a common service type.

Response (200 OK)

{
  "archetypes": [
    {
      "name": "python-lambda",
      "display_name": "Python Lambda service",
      "description": "AWS Lambda function in Python. Strict security gates; quality gates non-blocking."
    },
    {
      "name": "nodejs-service",
      "display_name": "Node.js service",
      "description": "Node.js or JavaScript service. Dependency and secret gates."
    },
    {
      "name": "terraform-iac",
      "display_name": "Terraform IaC repository",
      "description": "Terraform infrastructure repository. IaC security gates primary."
    },
    {
      "name": "oss-library",
      "display_name": "Open source library",
      "description": "OSS library. License and dependency gates; governance required."
    }
  ]
}

Archetype object fields

FieldTypeDescription
namestringArchetype identifier used in the instantiate endpoint path
display_namestringHuman-readable label shown in the Brief Wizard Quick Pick
descriptionstringShort description of the archetype's intent and primary gates

Example

curl https://api.ticketyboo.dev/v1/archetypes \
  -H "x-api-key: tbo-your-key-here"

POST /v1/archetypes/{name}/instantiate

POST /v1/archetypes/{name}/instantiate API key required

Generates a devcontract.json from the specified archetype, populated with the provided service name. The returned JSON is the complete contract file content, ready to write to the repository root.

Path parameters

ParameterDescription
nameArchetype name from the list endpoint (e.g. python-lambda)

Request body

FieldTypeRequiredDescription
service_namestringYesName of the service. Used as the service_name field in the generated contract.

Response (200 OK)

The response body is the complete devcontract.json content:

{
  "service_name": "my-api",
  "version": "1.0.0",
  "description": "Python Lambda service — generated from python-lambda archetype",
  "gates": [
    {
      "category": "secret",
      "severity": "high",
      "threshold": 0,
      "blocking": true,
      "description": "No secrets at high or critical severity"
    },
    {
      "category": "sast",
      "severity": "high",
      "threshold": 0,
      "blocking": true,
      "description": "No high or critical code vulnerabilities"
    },
    {
      "category": "dependency",
      "severity": "high",
      "threshold": 0,
      "blocking": true,
      "description": "No high or critical CVEs"
    }
  ]
}

Error responses

StatusCondition
400Missing service_name in request body
401Missing or invalid API key
404Archetype name not found

Example

curl -X POST https://api.ticketyboo.dev/v1/archetypes/python-lambda/instantiate \
  -H "Content-Type: application/json" \
  -H "x-api-key: tbo-your-key-here" \
  -d '{"service_name": "my-api"}'

Related