Spec Items API¶

Create, manage, and organize functional and technical spec items within a project.

Endpoints¶

Method	Path	Description
GET	`/projects/:id/spec/items`	List spec items
GET	`/projects/:id/spec/items/:item_id`	Get a spec item
POST	`/projects/:id/spec/items`	Create a spec item
PATCH	`/projects/:id/spec/items/:item_id`	Update a spec item
DELETE	`/projects/:id/spec/items/:item_id`	Delete a spec item
POST	`/projects/:id/spec/items/bulk`	Bulk create items
POST	`/projects/:id/spec/items/:item_id/transition`	Change item state
POST	`/projects/:id/spec/items/:item_id/transition_implementation`	Change implementation status
GET	`/projects/:id/graph/edges`	List dependency edges
POST	`/projects/:id/graph/edges`	Create a dependency edge
DELETE	`/projects/:id/graph/edges/:edge_id`	Delete a dependency edge
GET	`/projects/:id/graph/impact`	Impact analysis
GET	`/projects/:id/graph/dependencies/:item_id`	Items this item depends on
GET	`/projects/:id/graph/dependents/:item_id`	Items that depend on this item

List Spec Items¶

GET /projects/:id/spec/items

Query parameters

Parameter	Type	Description
`type_of`	string	Filter: `functional` or `technical`
`state`	string	Filter: `draft`, `inbox`, `accepted`, `rejected`
`implementation_status`	string	Filter: `pending`, `in_progress`, `implemented`, `verified`, `not_applicable`
`tag`	string	Filter by tag
`q`	string	Full-text search in title and description
`has_review`	boolean	Filter to items with an AI review
`review_verdict`	string	Filter: `pass`, `needs_work`, `fail`
`parent_id`	integer	Filter to children of a specific item
`sort`	string	Sort field; prefix with `-` for descending. Options: `created_at`, `updated_at`, `title`, `priority`
`page`	integer	Page number (default: 1)
`per`	integer	Items per page (default: 25, max: 100)

# List all accepted functional specs
curl "https://funcspec.net/api/v1/projects/42/spec/items?type_of=functional&state=accepted" \
  -H "X-Api-Key: $FUNCSPEC_API_KEY"

# Search for password-related specs
curl "https://funcspec.net/api/v1/projects/42/spec/items?q=password" \
  -H "X-Api-Key: $FUNCSPEC_API_KEY"

# Items tagged 'auth', sorted newest first
curl "https://funcspec.net/api/v1/projects/42/spec/items?tag=auth&sort=-created_at" \
  -H "X-Api-Key: $FUNCSPEC_API_KEY"

Response

{
  "data": [
    {
      "id": 15,
      "permalink": "F-1",
      "title": "User authentication",
      "type_of": "functional",
      "state": "accepted",
      "priority": "high",
      "tags": ["auth", "security"],
      "parent_id": null,
      "implementation_status": null,
      "has_review": true,
      "review_verdict": "pass",
      "created_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-03-15T14:32:11Z"
    }
  ],
  "meta": { "total": 24, "page": 1, "per": 25 }
}

Get a Spec Item¶

GET /projects/:id/spec/items/:item_id

curl https://funcspec.net/api/v1/projects/42/spec/items/15 \
  -H "X-Api-Key: $FUNCSPEC_API_KEY"

{
  "data": {
    "id": 15,
    "permalink": "F-1",
    "title": "User authentication",
    "type_of": "functional",
    "state": "accepted",
    "priority": "high",
    "tags": ["auth", "security"],
    "description": "Users can log in with their email address and password...",
    "description_plain": "Users can log in with their email address and password...",
    "parent_id": null,
    "implementation_status": null,
    "version": 4,
    "created_at": "2026-01-10T09:00:00Z",
    "updated_at": "2026-03-15T14:32:11Z"
  }
}

Create a Spec Item¶

POST /projects/:id/spec/items

Request body

Field	Type	Required	Description
`title`	string	Yes	Short summary
`type_of`	string	Yes	`functional` or `technical`
`description`	string	No	Full description (Markdown)
`state`	string	No	Initial state (default: `draft`)
`priority`	string	No	`low`, `medium`, `high`, `critical` (default: `medium`)
`tags`	array	No	Array of tag strings
`parent_id`	integer	No	ID of parent item

curl -X POST https://funcspec.net/api/v1/projects/42/spec/items \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "User password reset",
    "type_of": "functional",
    "description": "Users can request a password reset link sent to their email address.",
    "priority": "high",
    "tags": ["auth", "email"],
    "state": "draft"
  }'

Returns 201 Created with the created item.

Update a Spec Item¶

PATCH /projects/:id/spec/items/:item_id

All fields are optional.

curl -X PATCH https://funcspec.net/api/v1/projects/42/spec/items/15 \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "User authentication (email/password)",
    "priority": "critical",
    "tags": ["auth", "security", "core"]
  }'

Delete a Spec Item¶

DELETE /projects/:id/spec/items/:item_id

Warning

Permanently removes the item and all associated AI reviews, proposals, and dependency edges.

curl -X DELETE https://funcspec.net/api/v1/projects/42/spec/items/15 \
  -H "X-Api-Key: $FUNCSPEC_API_KEY"

Returns 204 No Content.

Bulk Create¶

POST /projects/:id/spec/items/bulk

Create multiple spec items in a single request. Useful for importing specifications.

Request body

curl -X POST https://funcspec.net/api/v1/projects/42/spec/items/bulk \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "title": "User registration", "type_of": "functional", "priority": "high" },
      { "title": "Email verification", "type_of": "functional", "priority": "high" },
      { "title": "User profile management", "type_of": "functional", "priority": "medium" }
    ]
  }'

{
  "data": {
    "created": 3,
    "items": [
      { "id": 20, "permalink": "F-5", "title": "User registration" },
      { "id": 21, "permalink": "F-6", "title": "Email verification" },
      { "id": 22, "permalink": "F-7", "title": "User profile management" }
    ]
  }
}

Transition State¶

POST /projects/:id/spec/items/:item_id/transition

Change an item's lifecycle state.

Request body

Field	Type	Required	Description
`state`	string	Yes	Target state: `draft`, `inbox`, `accepted`, `rejected`

curl -X POST https://funcspec.net/api/v1/projects/42/spec/items/15/transition \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "accepted"}'

Transition Implementation Status¶

POST /projects/:id/spec/items/:item_id/transition_implementation

Update the implementation status of a technical spec.

Request body

Field	Type	Required	Description
`status`	string	Yes	`pending`, `in_progress`, `implemented`, `verified`, `not_applicable`
`note`	string	No	Optional note for context

curl -X POST https://funcspec.net/api/v1/projects/42/spec/items/28/transition_implementation \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "implemented",
    "note": "Merged in PR #142"
  }'

Dependency Edges¶

Edges represent directed relationships between spec items. The most common relationship is a technical spec "implementing" a functional spec.

List edges¶

GET /projects/:id/graph/edges

curl https://funcspec.net/api/v1/projects/42/graph/edges \
  -H "X-Api-Key: $FUNCSPEC_API_KEY"

{
  "data": [
    {
      "id": 5,
      "source_id": 28,
      "source_permalink": "T-3",
      "target_id": 15,
      "target_permalink": "F-1",
      "relationship": "implements"
    }
  ],
  "meta": { "total": 18, "page": 1, "per": 25 }
}

Create an edge¶

POST /projects/:id/graph/edges

curl -X POST https://funcspec.net/api/v1/projects/42/graph/edges \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": 28,
    "target_id": 15
  }'

Delete an edge¶

DELETE /projects/:id/graph/edges/:edge_id

curl -X DELETE https://funcspec.net/api/v1/projects/42/graph/edges/5 \
  -H "X-Api-Key: $FUNCSPEC_API_KEY"

Impact Analysis¶

GET /projects/:id/graph/impact

Returns a summary of which functional specs have technical spec coverage and which are uncovered.

curl https://funcspec.net/api/v1/projects/42/graph/impact \
  -H "X-Api-Key: $FUNCSPEC_API_KEY"

{
  "data": {
    "covered": [
      { "id": 15, "permalink": "F-1", "title": "User authentication", "technical_count": 4 }
    ],
    "uncovered": [
      { "id": 22, "permalink": "F-7", "title": "User profile management" }
    ],
    "coverage_percentage": 78
  }
}

Item Dependencies¶

Dependencies (what this item depends on)¶

GET /projects/:id/graph/dependencies/:item_id

curl https://funcspec.net/api/v1/projects/42/graph/dependencies/28 \
  -H "X-Api-Key: $FUNCSPEC_API_KEY"

Dependents (what depends on this item)¶

GET /projects/:id/graph/dependents/:item_id

curl https://funcspec.net/api/v1/projects/42/graph/dependents/15 \
  -H "X-Api-Key: $FUNCSPEC_API_KEY"

Both return an array of spec item summaries.