AI Operations API¶

Trigger AI operations on spec items and manage the resulting proposals and reviews.

Endpoints¶

Method	Path	Description
POST	`/projects/:id/work_package/:item_id/review`	AI review a single item
POST	`/projects/:id/work_package/review_all`	Batch review all accepted items
POST	`/projects/:id/work_package/:item_id/propose`	Generate AI improvement proposal
POST	`/projects/:id/work_package/:item_id/accept`	Accept a pending proposal
POST	`/projects/:id/work_package/:item_id/reject`	Reject a pending proposal
POST	`/projects/:id/work_package/apply_all`	Accept all pending proposals
POST	`/projects/:id/work_package/:item_id/generate_tech`	Generate tech spec proposals
POST	`/projects/:id/work_package/:item_id/create_tech`	Create a generated tech spec
POST	`/projects/:id/work_package/:item_id/func_review`	Functional review
POST	`/projects/:id/work_package/func_review_all`	Batch functional review
POST	`/projects/:id/work_package/:item_id/audit`	Code audit
POST	`/projects/:id/work_package/audit_all`	Batch code audit
GET	`/projects/:id/spec/items/:item_id/audit_results`	Get audit results

Note

All AI operations are synchronous for single-item endpoints and asynchronous for batch endpoints. Single-item calls return results directly; batch calls return a job reference and process in the background.

AI Review¶

POST /projects/:id/work_package/:item_id/review

Analyzes the spec item for coverage, gaps, and quality.

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

Response

{
  "data": {
    "item_id": 15,
    "permalink": "F-1",
    "coverage_score": 72,
    "verdict": "needs_work",
    "gaps": [
      "No error handling specified for invalid email addresses",
      "Password reset token expiry not mentioned",
      "Behavior when user account is locked is undefined"
    ],
    "suggestions": [
      "Specify the token validity window (recommend 1 hour)",
      "Define what happens on expired token use",
      "Clarify whether the old password is invalidated immediately"
    ],
    "reviewed_at": "2026-03-15T14:32:11Z"
  }
}

Verdict values

Verdict	Meaning
`pass`	Spec is well-defined and complete
`needs_work`	Notable gaps exist but the core is solid
`fail`	Spec is too incomplete or ambiguous to be useful

Batch Review All¶

POST /projects/:id/work_package/review_all

Queues AI reviews for all accepted spec items in the project.

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

{
  "data": {
    "job_id": "job_abc123",
    "queued_count": 62,
    "status": "queued",
    "message": "62 items queued for review. Results will be available as each completes."
  }
}

AI Improve — Generate Proposal¶

POST /projects/:id/work_package/:item_id/propose

Generates a rewritten description for the spec item, addressing gaps from a prior review.

Tip

Run a review first. The proposal quality is significantly higher when the AI has review results to work from.

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

{
  "data": {
    "item_id": 15,
    "permalink": "F-1",
    "current_description": "Users can log in with email and password.",
    "proposed_description": "Users can log in using their registered email address and password.\n\n## Requirements\n\n- Email addresses are normalized to lowercase before comparison\n- Failed attempts show a generic error (do not reveal whether email exists)\n- Accounts are locked after 5 consecutive failed attempts for 15 minutes\n- Successful login redirects to the user's last visited page, or the dashboard\n\n## Session Behavior\n\n- Sessions expire after 24 hours of inactivity\n- \"Remember me\" extends the session to 30 days\n- Users can view and revoke active sessions in Account Settings",
    "status": "pending",
    "created_at": "2026-03-15T14:35:00Z"
  }
}

Accept a Proposal¶

POST /projects/:id/work_package/:item_id/accept

Applies the pending proposal, replacing the item's description with the AI-generated version.

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

{
  "data": {
    "item_id": 15,
    "permalink": "F-1",
    "status": "accepted",
    "applied_at": "2026-03-15T14:36:00Z"
  }
}

Reject a Proposal¶

POST /projects/:id/work_package/:item_id/reject

Discards the pending proposal without modifying the spec item.

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

Apply All Proposals¶

POST /projects/:id/work_package/apply_all

Accepts all currently pending proposals in the project.

Warning

This modifies the description of every spec item that has a pending proposal. Review pending proposals individually before using this endpoint.

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

{
  "data": {
    "applied_count": 18,
    "status": "complete"
  }
}

Generate Tech Specs¶

POST /projects/:id/work_package/:item_id/generate_tech

Analyzes a functional spec and generates a list of proposed technical spec items.

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

{
  "data": {
    "functional_item_id": 15,
    "functional_permalink": "F-1",
    "proposals": [
      {
        "index": 0,
        "title": "User model authentication fields",
        "description": "Add `password_digest`, `remember_token`, and `locked_until` fields to the `users` table. Use `has_secure_password` for bcrypt hashing."
      },
      {
        "index": 1,
        "title": "Authentication controller (sessions)",
        "description": "Implement `SessionsController` with `create` and `destroy` actions. Apply rate limiting of 5 attempts per 15 minutes per IP."
      },
      {
        "index": 2,
        "title": "Account lockout service",
        "description": "Create `AccountLockoutService` to track failed attempts and lock accounts. Unlock via background job after 15 minutes."
      }
    ]
  }
}

Create a Generated Tech Spec¶

POST /projects/:id/work_package/:item_id/create_tech

Creates one of the proposed technical specs as a real spec item, linked to the parent functional spec.

Request body

Field	Type	Required	Description
`index`	integer	Yes	Index of the proposal from the generate_tech response

curl -X POST https://funcspec.net/api/v1/projects/42/work_package/15/create_tech \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"index": 0}'

{
  "data": {
    "id": 88,
    "permalink": "T-12",
    "title": "User model authentication fields",
    "type_of": "technical",
    "state": "draft",
    "parent_id": 15,
    "created_at": "2026-03-15T14:40:00Z"
  }
}

Functional Review¶

POST /projects/:id/work_package/:item_id/func_review

Reviews a functional spec from a product requirements perspective, identifying ambiguity, contradictions, and missing edge cases.

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

{
  "data": {
    "item_id": 15,
    "permalink": "F-1",
    "issues": [
      {
        "severity": "high",
        "type": "ambiguity",
        "description": "\"Remember me\" behavior is not defined — duration and device scope are unspecified"
      },
      {
        "severity": "medium",
        "type": "missing_edge_case",
        "description": "No requirement for what happens if a user tries to log in while already logged in on the same device"
      }
    ],
    "reviewed_at": "2026-03-15T14:32:11Z"
  }
}

Batch functional review all¶

POST /projects/:id/work_package/func_review_all

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

Code Audit¶

POST /projects/:id/work_package/:item_id/audit

Audits a technical spec against the connected GitHub repository. Requires a GitHub repository to be configured on the project.

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

{
  "data": {
    "item_id": 28,
    "permalink": "T-3",
    "status": "partial",
    "findings": [
      {
        "type": "implemented",
        "severity": "info",
        "detail": "SessionsController found at app/controllers/sessions_controller.rb"
      },
      {
        "type": "divergence",
        "severity": "warning",
        "detail": "Rate limit is 10 attempts in code; spec requires 5 attempts per 15 minutes"
      },
      {
        "type": "missing",
        "severity": "error",
        "detail": "Account lockout via `locked_until` field not found in users schema"
      }
    ],
    "audited_at": "2026-03-15T14:45:00Z"
  }
}

Audit status values

Status	Description
`implemented`	Spec appears to be fully implemented
`partial`	Some requirements implemented, others missing or divergent
`not_found`	No matching code found for this spec
`divergent`	Code exists but differs significantly from the spec

Finding types

Type	Description
`implemented`	Requirement found in codebase
`missing`	No code found for this requirement
`divergence`	Code found but differs from spec

Batch audit all¶

POST /projects/:id/work_package/audit_all

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

Get Audit Results¶

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

Retrieve stored audit results for an item without triggering a new audit.

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

Returns the same format as the audit response above, plus audited_at timestamp.

If no audit has been run yet, returns 404.