Specs API

Create Spec

Create a new specification.

POST /v1/specs

Request Body

{
  "specId": "AUTH-001",
  "title": "User Authentication",
  "content": "# Authentication\n\nImplement user auth...",
  "status": "pending",
  "agent": "claude"
}

Response

{
  "spec": {
    "id": 1,
    "specId": "AUTH-001",
    "title": "User Authentication",
    "status": "pending",
    "createdAt": "2025-12-08T...",
    "updatedAt": "2025-12-08T..."
  }
}

Example

curl -X POST \
  -H "Authorization: Bearer sk_admin_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "specId": "AUTH-001",
    "title": "User Authentication",
    "content": "# Auth Spec\n\nImplement authentication.",
    "status": "pending"
  }' \
  http://localhost:3000/conduct/v1/specs

List Specs

Get all specifications.

GET /v1/specs

Query Parameters

• status - Filter by status
• limit - Results per page (default: 20)
• cursor - Pagination cursor

Response

{
  "specs": [
    {
      "id": 1,
      "specId": "AUTH-001",
      "title": "User Authentication",
      "status": "pending",
      "createdAt": "2025-12-08T..."
    }
  ],
  "meta": {
    "total": 42,
    "hasMore": true,
    "nextCursor": "abc123"
  }
}

Example

curl -H "Authorization: Bearer sk_admin_xxx" \
  "http://localhost:3000/conduct/v1/specs?status=draft&limit=10"

Get Spec

Get a specific specification.

GET /v1/specs/:specId

Response

{
  "spec": {
    "id": 1,
    "specId": "AUTH-001",
    "title": "User Authentication",
    "content": "# Auth Spec\n\nImplement authentication.",
    "status": "pending",
    "createdAt": "2025-12-08T...",
    "updatedAt": "2025-12-08T..."
  }
}

Example

curl -H "Authorization: Bearer sk_admin_xxx" \
  http://localhost:3000/conduct/v1/specs/AUTH-001

Update Spec

Update a specification.

PATCH /v1/specs/:specId

Request Body

{
  "title": "Updated Title",
  "status": "completed",
  "content": "Updated content..."
}

All fields are optional.

Response

{
  "spec": {
    "id": 1,
    "specId": "AUTH-001",
    "title": "Updated Title",
    "status": "completed",
    "updatedAt": "2025-12-08T..."
  }
}

Example

curl -X PATCH \
  -H "Authorization: Bearer sk_admin_xxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}' \
  http://localhost:3000/conduct/v1/specs/AUTH-001

Delete Spec

Delete a specification.

DELETE /v1/specs/:specId

Response

{
  "message": "Spec deleted successfully"
}

Example

curl -X DELETE \
  -H "Authorization: Bearer sk_admin_xxx" \
  http://localhost:3000/conduct/v1/specs/AUTH-001

Get Spec Runs

Get all runs for a specification.

GET /v1/specs/:specId/runs

Response

{
  "runs": [
    {
      "id": 1,
      "runId": "RUN-001",
      "specId": "AUTH-001",
      "status": "completed",
      "createdAt": "2025-12-08T..."
    }
  ]
}

Example

curl -H "Authorization: Bearer sk_admin_xxx" \
  http://localhost:3000/conduct/v1/specs/AUTH-001/runs

Status Values

Valid status values:

• pending - Not started
• draft - In progress
• in_progress - Being implemented
• completed - Finished
• cancelled - Abandoned

Validation

Required Fields

• specId - Must be unique, alphanumeric with hyphens
• title - Non-empty string
• content - Non-empty string

Optional Fields

• status - One of valid status values (default: pending)
• agent - Agent name (string)

Error Responses

400 Bad Request

{
  "error": "Invalid request",
  "code": "BAD_REQUEST"
}

409 Conflict

{
  "error": "Spec with ID 'AUTH-001' already exists",
  "code": "CONFLICT"
}

404 Not Found

{
  "error": "Spec not found",
  "code": "NOT_FOUND"
}