Projects API¶

Manage projects, export documentation, and retrieve project-level data.

Endpoints¶

Method	Path	Description
GET	`/projects`	List projects
GET	`/projects/:id`	Get a project
POST	`/projects`	Create a project
PATCH	`/projects/:id`	Update a project
DELETE	`/projects/:id`	Delete a project
GET	`/projects/:id/stats`	Project statistics
GET	`/projects/:id/graph`	Dependency graph
GET	`/projects/:id/export/markdown`	Export as Markdown
GET	`/projects/:id/export/json`	Export as JSON
GET	`/projects/:id/export/html`	Export as HTML
GET	`/projects/:id/export/pdf`	Export as PDF
GET	`/projects/:id/audit`	Audit log
GET	`/projects/:id/usage`	Usage summary
GET	`/projects/:id/inbox`	Inbox items

List Projects¶

GET /projects

Returns all projects the authenticated user has access to.

Response

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

{
  "data": [
    {
      "id": 42,
      "name": "Payments Service",
      "slug": "payments-service",
      "description": "Stripe integration and billing workflows",
      "organization": {
        "id": 7,
        "name": "Acme Corp",
        "slug": "acme"
      },
      "stats": {
        "functional_count": 24,
        "technical_count": 51,
        "accepted_count": 60
      },
      "created_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-03-15T14:32:11Z"
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "per": 25
  }
}

Get a Project¶

GET /projects/:id

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

{
  "data": {
    "id": 42,
    "name": "Payments Service",
    "slug": "payments-service",
    "description": "Stripe integration and billing workflows",
    "organization": { "id": 7, "name": "Acme Corp", "slug": "acme" },
    "github_repo": "acme/payments-service",
    "created_at": "2026-01-10T09:00:00Z",
    "updated_at": "2026-03-15T14:32:11Z"
  }
}

Create a Project¶

POST /projects

Request body

Field	Type	Required	Description
`name`	string	Yes	Project display name
`description`	string	No	Brief project description
`slug`	string	No	URL slug (auto-generated if omitted)
`organization_id`	integer	No	Target org (defaults to your primary org)

curl -X POST https://funcspec.net/api/v1/projects \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payments Service",
    "description": "Stripe integration and billing workflows",
    "slug": "payments-service"
  }'

Returns 201 Created with the new project.

Update a Project¶

PATCH /projects/:id

All fields are optional — only include the ones you want to change.

curl -X PATCH https://funcspec.net/api/v1/projects/42 \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payments & Billing",
    "description": "Updated description"
  }'

Delete a Project¶

DELETE /projects/:id

Danger

Permanently deletes the project and all its spec items, AI reviews, dependency edges, and history. This cannot be undone.

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

Returns 204 No Content on success.

Project Statistics¶

GET /projects/:id/stats

Returns counts and coverage metrics for the project.

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

{
  "data": {
    "spec_items": {
      "total": 75,
      "functional": 24,
      "technical": 51
    },
    "by_state": {
      "draft": 5,
      "inbox": 3,
      "accepted": 62,
      "rejected": 5
    },
    "implementation": {
      "pending": 18,
      "in_progress": 12,
      "implemented": 28,
      "verified": 4
    },
    "ai_reviews": {
      "reviewed": 58,
      "avg_coverage_score": 81,
      "pass": 42,
      "needs_work": 14,
      "fail": 2
    }
  }
}

Dependency Graph¶

GET /projects/:id/graph

Returns all spec items with their dependency edges, suitable for rendering a dependency graph.

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

{
  "data": {
    "nodes": [
      { "id": 1, "permalink": "F-1", "title": "User authentication", "type_of": "functional" },
      { "id": 10, "permalink": "T-1", "title": "Auth controller", "type_of": "technical" }
    ],
    "edges": [
      { "id": 5, "source_id": 10, "target_id": 1, "relationship": "implements" }
    ]
  }
}

Export¶

Export endpoints return document content directly (not JSON), suitable for download.

Markdown Export¶

GET /projects/:id/export/markdown

curl https://funcspec.net/api/v1/projects/42/export/markdown \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -o specs.md

JSON Export¶

GET /projects/:id/export/json

Returns structured JSON with all spec items, suitable for import into other tools.

curl https://funcspec.net/api/v1/projects/42/export/json \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -o specs.json

HTML Export¶

GET /projects/:id/export/html

Returns a self-contained HTML document.

curl https://funcspec.net/api/v1/projects/42/export/html \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -o specs.html

PDF Export¶

GET /projects/:id/export/pdf

Returns a PDF document.

curl https://funcspec.net/api/v1/projects/42/export/pdf \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -o specs.pdf

Audit Log¶

GET /projects/:id/audit

Returns a paginated list of audit events for the project.

Query parameters

Parameter	Description
`page`	Page number
`per`	Items per page (max 100)

curl "https://funcspec.net/api/v1/projects/42/audit?per=50" \
  -H "X-Api-Key: $FUNCSPEC_API_KEY"

{
  "data": [
    {
      "id": 1024,
      "timestamp": "2026-03-15T14:32:11Z",
      "actor": "alice@acme.com",
      "action": "transition",
      "target_type": "SpecItem",
      "target_id": 15,
      "target_permalink": "F-15",
      "details": { "from": "inbox", "to": "accepted" }
    }
  ],
  "meta": { "total": 842, "page": 1, "per": 25 }
}

Usage Summary¶

GET /projects/:id/usage

Returns AI operation usage counts for the current billing period.

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

{
  "data": {
    "period": {
      "start": "2026-03-01T00:00:00Z",
      "end": "2026-03-31T23:59:59Z"
    },
    "operations": {
      "review": 48,
      "improve": 32,
      "generate_tech": 15,
      "func_review": 20,
      "audit": 12
    },
    "total_credits": 157
  }
}

Inbox¶

GET /projects/:id/inbox

Returns spec items currently in the inbox state, awaiting triage.

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

{
  "data": [
    {
      "id": 88,
      "permalink": "F-22",
      "title": "Guest checkout flow",
      "type_of": "functional",
      "state": "inbox",
      "created_at": "2026-03-29T10:00:00Z"
    }
  ],
  "meta": { "total": 3, "page": 1, "per": 25 }
}