> ## Documentation Index
> Fetch the complete documentation index at: https://acai.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Write feature states

> Record implementation-specific progress for one feature in one implementation. State writes do not change requirement text or code refs; they only capture how this implementation currently evaluates each requirement, for example assigned, blocked, completed, or accepted. On first write, local state starts from the parent implementation when one exists, then applies the incoming changes. Use this after analysis, coding, review, or QA to record progress without changing branch-derived truth.



## OpenAPI

````yaml /openapi.json patch /feature-states
openapi: 3.0.0
info:
  description: >-
    Acai is an API for spec-driven development across git branches and product
    implementations. Specs store canonical requirement definitions, refs store
    where code on a branch appears to implement those requirements, and states
    store implementation-specific progress such as completed, blocked, or
    accepted. Agents typically discover an implementation, read canonical
    feature context, sync branch-derived changes, and then record status updates
    separately.
  title: Acai API
  version: 1.0.0
servers:
  - description: API v1
    url: http://localhost:4000/api/v1
    variables: {}
security:
  - bearerAuth: []
tags:
  - description: >-
      Endpoints for syncing branch-derived truth, resolving canonical feature
      context, discovering implementation work, and recording
      implementation-specific progress. The API keeps specs and refs separate
      from status updates so agents can read shared requirements, push observed
      code changes, and write progress without mixing those concerns.
    name: Actions
paths:
  /feature-states:
    patch:
      tags:
        - Actions
      summary: Write feature states
      description: >-
        Record implementation-specific progress for one feature in one
        implementation. State writes do not change requirement text or code
        refs; they only capture how this implementation currently evaluates each
        requirement, for example assigned, blocked, completed, or accepted. On
        first write, local state starts from the parent implementation when one
        exists, then applies the incoming changes. Use this after analysis,
        coding, review, or QA to record progress without changing branch-derived
        truth.
      operationId: AcaiWeb.Api.FeatureStatesController.update
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeatureStatesRequest'
        description: Feature states request body
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureStatesResponse'
          description: Feature states written
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Payload too large
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limit exceeded
      callbacks: {}
      security:
        - bearerAuth: []
components:
  schemas:
    FeatureStatesRequest:
      properties:
        feature_name:
          type: string
        implementation_name:
          type: string
        product_name:
          type: string
        states:
          additionalProperties:
            allOf:
              - properties:
                  comment:
                    description: Optional state comment
                    type: string
                  status:
                    description: Nullable state status
                    enum:
                      - assigned
                      - blocked
                      - incomplete
                      - completed
                      - rejected
                      - accepted
                    nullable: true
                    type: string
                required:
                  - status
                title: FeatureStateObject
                type: object
          minProperties: 1
          type: object
      required:
        - product_name
        - feature_name
        - implementation_name
        - states
      title: FeatureStatesRequest
      type: object
    FeatureStatesResponse:
      properties:
        data:
          allOf:
            - properties:
                feature_name:
                  type: string
                implementation_id:
                  type: string
                implementation_name:
                  type: string
                product_name:
                  type: string
                states_written:
                  type: integer
                warnings:
                  items:
                    type: string
                  type: array
              required:
                - product_name
                - feature_name
                - implementation_name
                - implementation_id
                - states_written
                - warnings
              title: FeatureStatesResponseData
              type: object
      required:
        - data
      title: FeatureStatesResponse
      type: object
    ErrorResponse:
      properties:
        errors:
          properties:
            detail:
              type: string
            status:
              type: string
          required:
            - detail
          type: object
      required:
        - errors
      title: ErrorResponse
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: API token
      scheme: bearer
      type: http

````