intentdocs-com Sync API

openapi: 3.2.0
info:
  title: Intentdocs Com Sync API
  version: '2026-08-22'
  contact:
    name: IntentDocs Support
    url: https://intentdocs.com
    email: support@intentdocs.com
  license:
    name: Proprietary
    url: https://intentdocs.com/terms
  x-api-version: '2026-08-22'
  x-deprecation-policy: Breaking changes are announced at least 90 days before removal. Deprecated endpoints return a Deprecation header with the sunset date. Subscribe to the changelog at https://intentdocs.com/blog for updates.
  description: 'Operations tagged Sync across 2 of this provider''s published API definitions: openapi.json, intentdocs-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://intentdocs.com
  description: Production server
- url: http://localhost:3000
  description: Development server
tags:
- name: Sync
  description: Sync API for external tools to read/write story maps, log activities, and report progress
paths:
  /api/sync/{mapId}/stories:
    get:
      operationId: listStories
      tags:
      - Sync
      summary: List stories for a map
      description: Retrieve all user stories from a story map, grouped by release with status summaries.
      parameters:
      - name: mapId
        in: path
        required: true
        schema:
          type: string
        description: Story map id — from .intent/config.json; the caller is named by the CLI bearer
      responses:
        '200':
          description: Stories retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  map:
                    type: object
                    properties:
                      id:
                        type: string
                      title:
                        type: string
                  stories:
                    type: array
                    items:
                      $ref: '#/components/schemas/Story'
                  summary:
                    type: object
                    properties:
                      total:
                        type: number
                      todo:
                        type: number
                      in_progress:
                        type: number
                      needs_rework:
                        type: number
                      done:
                        type: number
                      approved:
                        type: number
        '401':
          description: No CLI bearer, or the bearer's holder has no standing on the map's project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createStories
      tags:
      - Sync
      summary: Create new stories
      description: Bulk create new user stories for a story map.
      parameters:
      - name: mapId
        in: path
        required: true
        schema:
          type: string
        description: Story map id — from .intent/config.json; the caller is named by the CLI bearer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - stories
              properties:
                stories:
                  type: array
                  items:
                    type: object
                    required:
                    - title
                    properties:
                      title:
                        type: string
                      activity:
                        type: string
                      as_a:
                        type: string
                      i_want:
                        type: string
                      so_that:
                        type: string
                      priority:
                        enum:
                        - must
                        - should
                        - could
                      effort:
                        enum:
                        - XS
                        - S
                        - M
                        - L
                        - XL
                      release_order:
                        type: number
                      acceptance_criteria:
                        type: array
                        items:
                          oneOf:
                          - type: string
                          - $ref: '#/components/schemas/AcceptanceCriterion'
      responses:
        '201':
          description: Stories created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  created:
                    type: number
                  stories:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                        activity:
                          type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: No CLI bearer, or no standing on the map's project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: updateStories
      tags:
      - Sync
      summary: Update story status and metadata
      description: Update multiple stories with new status, notes, implementation details, and screenshots.
      parameters:
      - name: mapId
        in: path
        required: true
        schema:
          type: string
        description: Story map id — from .intent/config.json; the caller is named by the CLI bearer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - stories
              properties:
                stories:
                  type: array
                  items:
                    type: object
                    required:
                    - id
                    properties:
                      id:
                        type: string
                      status:
                        enum:
                        - todo
                        - in_progress
                        - needs_rework
                        - done
                        - approved
                      notes:
                        type: string
                      implementation_summary:
                        type: string
                      implemented_files:
                        type: array
                        items:
                          type: string
                      screenshot_url:
                        type: string
                      implementation_plan:
                        type: object
                      cancelled_at:
                        type:
                        - string
                        - 'null'
                      cancellation_reason:
                        type:
                        - string
                        - 'null'
                      pr_url:
                        type: string
                      pr_number:
                        type: number
                      forced:
                        type: boolean
                        description: Set when overriding failed must-criteria
      responses:
        '200':
          description: Stories updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  updated:
                    type: number
                  stories:
                    type: array
                  readyReleases:
                    type: array
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: No CLI bearer, or no standing on the map's project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://intentdocs.com
      description: Production server
    - url: http://localhost:3000
      description: Development server
  /api/sync/{mapId}/context:
    get:
      operationId: getStoryMapContext
      tags:
      - Sync
      summary: Get story map context as INTENT.md
      description: Retrieve the current story map state as a Markdown document (INTENT.md format) for use in AI development tools.
      parameters:
      - name: mapId
        in: path
        required: true
        schema:
          type: string
        description: Story map id — from .intent/config.json; the caller is named by the CLI bearer
      responses:
        '200':
          description: INTENT.md context document
          content:
            text/markdown:
              schema:
                type: string
        '401':
          description: No CLI bearer, or the bearer's holder has no standing on the map's project
          content:
            text/plain:
              schema:
                type: string
    servers:
    - url: https://intentdocs.com
      description: Production server
    - url: http://localhost:3000
      description: Development server
  /api/sync/{mapId}/activity:
    get:
      operationId: getRecentActivity
      tags:
      - Sync
      summary: Get recent project activity
      description: Retrieve recent activity events from the project (up to 20 most recent).
      parameters:
      - name: mapId
        in: path
        required: true
        schema:
          type: string
        description: Story map id — from .intent/config.json; the caller is named by the CLI bearer
      responses:
        '200':
          description: Activity log retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  activity:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        event_type:
                          type: string
                        summary:
                          type: string
                        metadata:
                          type: object
                        source:
                          type: string
                        created_at:
                          type: string
        '401':
          description: No CLI bearer, or the bearer's holder has no standing on the map's project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Map not linked to a project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: logActivity
      tags:
      - Sync
      summary: Log an activity event
      description: Record a custom event from CLI or external tools.
      parameters:
      - name: mapId
        in: path
        required: true
        schema:
          type: string
        description: Story map id — from .intent/config.json; the caller is named by the CLI bearer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - event_type
              - summary
              properties:
                event_type:
                  type: string
                summary:
                  type: string
                metadata:
                  type: object
                source:
                  type: string
                  default: cli
      responses:
        '201':
          description: Activity logged successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        '400':
          description: Missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: No CLI bearer, or the bearer's holder has no standing on the map's project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://intentdocs.com
      description: Production server
    - url: http://localhost:3000
      description: Development server
  /api/sync/{mapId}/build-order:
    get:
      operationId: getBuildOrder
      tags:
      - Sync
      summary: Get implementation build order
      description: Retrieve the suggested or manual build order for stories, including dependency information and AI reasoning.
      parameters:
      - name: mapId
        in: path
        required: true
        schema:
          type: string
        description: Story map id — from .intent/config.json; the caller is named by the CLI bearer
      responses:
        '200':
          description: Build order retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    type: array
                    items:
                      $ref: '#/components/schemas/BuildOrderStory'
                  generated_at:
                    type:
                    - string
                    - 'null'
                  mode:
                    enum:
                    - ai
                    - manual
                    - unset
        '401':
          description: No CLI bearer, or the bearer's holder has no standing on the map's project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateBuildOrder
      tags:
      - Sync
      summary: Update build sequence
      description: Set a custom implementation order for stories.
      parameters:
      - name: mapId
        in: path
        required: true
        schema:
          type: string
        description: Story map id — from .intent/config.json; the caller is named by the CLI bearer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - order
              properties:
                order:
                  type: array
                  items:
                    type: string
                  description: Ordered list of story IDs
      responses:
        '200':
          description: Build order updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    type: array
                    items:
                      $ref: '#/components/schemas/BuildOrderStory'
                  generated_at:
                    type:
                    - string
                    - 'null'
                  mode:
                    enum:
                    - manual
        '400':
          description: Invalid story IDs or order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: No CLI bearer, or no standing on the map's project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://intentdocs.com
      description: Production server
    - url: http://localhost:3000
      description: Development server
  /api/sync/{mapId}/blocker:
    post:
      operationId: raiseBlocker
      tags:
      - Sync
      summary: Raise a blocker on a story
      description: Escalate a must-criterion that has failed repeated fix attempts, signaling need for architectural decision.
      parameters:
      - name: mapId
        in: path
        required: true
        schema:
          type: string
        description: Story map id — from .intent/config.json; the caller is named by the CLI bearer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - story_id
              - summary
              - attempting
              - failing
              - decision_needed
              properties:
                story_id:
                  type: string
                criterion_id:
                  type: string
                summary:
                  type: string
                attempting:
                  type: string
                failing:
                  type: string
                decision_needed:
                  type: string
                attempts:
                  type: number
                  minimum: 1
      responses:
        '201':
          description: Blocker raised successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  blocker:
                    type: object
                    properties:
                      summary:
                        type: string
                      attempting:
                        type: string
                      failing:
                        type: string
                      decision_needed:
                        type: string
                      attempts:
                        type: number
                      created_at:
                        type: string
                      resolved_at:
                        type:
                        - string
                        - 'null'
        '400':
          description: Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: No CLI bearer, or the bearer's holder has no standing on the map's project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Story not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://intentdocs.com
      description: Production server
    - url: http://localhost:3000
      description: Development server
  /api/sync/{mapId}/decisions:
    get:
      operationId: listDecisions
      tags:
      - Sync
      summary: List decisions logged for a map
      description: Retrieve all architectural and product decisions made during development.
      parameters:
      - name: mapId
        in: path
        required: true
        schema:
          type: string
        description: Story map id — from .intent/config.json; the caller is named by the CLI bearer
      responses:
        '200':
          description: Decisions retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  decisions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Decision'
        '401':
          description: No CLI bearer, or the bearer's holder has no standing on the map's project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: logDecision
      tags:
      - Sync
      summary: Log a decision
      description: Record an architectural or product decision.
      parameters:
      - name: mapId
        in: path
        required: true
        schema:
          type: string
        description: Story map id — from .intent/config.json; the caller is named by the CLI bearer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - title
              - description
              properties:
                title:
                  type: string
                description:
                  type: string
                category:
                  enum:
                  - architecture
                  - product
                  - technical
                  - trade-off
                  default: technical
                story_id:
                  type: string
      responses:
        '201':
          description: Decision logged successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  title:
                    type: string
        '400':
          description: Missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: No CLI bearer, or the bearer's holder has no standing on the map's project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://intentdocs.com
      description: Production server
    - url: http://localhost:3000
      description: Development server
  /api/sync/{mapId}/screenshots:
    post:
      operationId: uploadScreenshot
      tags:
      - Sync
      summary: Upload product screenshot
      description: Upload a screenshot of implemented work. Returns a public URL for attaching to stories.
      parameters:
      - name: mapId
        in: path
        required: true
        schema:
          type: string
        description: Story map id — from .intent/config.json; the caller is named by the CLI bearer
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - story_id
              - image
              properties:
                story_id:
                  type: string
                image:
                  type: string
                  format: binary
                  description: PNG, JPEG, or WebP image (max 5MB)
      responses:
        '201':
          description: Screenshot uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
        '400':
          description: Invalid image or missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: No CLI bearer, or the bearer's holder has no standing on the map's project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Story not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://intentdocs.com
      description: Production server
    - url: http://localhost:3000
      description: Development server
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code (e.g. unauthorized, not_found, bad_request)
            message:
              type: string
              description: Human-readable error description
            hint:
              type: string
              description: Actionable suggestion for resolving the error
    BuildOrderStory:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        activity:
          type: string
        effort:
          enum:
          - XS
          - S
          - M
          - L
          - XL
        priority:
          enum:
          - must
          - should
          - could
        status:
          enum:
          - todo
          - in_progress
          - needs_rework
          - done
          - approved
        build_sequence:
          type:
          - number
          - 'null'
        depends_on:
          type: array
          items:
            type: string
        reason:
          type:
          - string
          - 'null'
    Story:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        activity:
          type: string
        user_story:
          type:
          - string
          - 'null'
        priority:
          enum:
          - must
          - should
          - could
        effort:
          enum:
          - XS
          - S
          - M
          - L
          - XL
        release:
          type: number
        build_sequence:
          type:
          - number
          - 'null'
        status:
          enum:
          - todo
          - in_progress
          - needs_rework
          - done
          - approved
        acceptance_criteria:
          type: array
          items:
            $ref: '#/components/schemas/AcceptanceCriterion'
        depends_on:
          type: array
          items:
            type: string
        notes:
          type:
          - string
          - 'null'
        implementation_plan:
          type:
          - object
          - 'null'
        cancelled_at:
          type:
          - string
          - 'null'
        cancellation_reason:
          type:
          - string
          - 'null'
    Decision:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        category:
          enum:
          - architecture
          - product
          - technical
          - trade-off
        story_id:
          type:
          - string
          - 'null'
        created_at:
          type: string
    AcceptanceCriterion:
      type: object
      properties:
        id:
          type: string
        text:
          type: string
        done:
          type: boolean
        given:
          type:
          - string
          - 'null'
        when:
          type:
          - string
          - 'null'
        then:
          type:
          - string
          - 'null'
        priority:
          type:
          - string
          - 'null'
        verification:
          type:
          - string
          - 'null'
        last_result:
          type:
          - string
          - 'null'
  securitySchemes:
    bearerAuth:
      type: oauth2
      description: OAuth 2.1 bearer token. Obtain via /api/oauth/authorize → /api/oauth/token flow, or use intent_cli_* tokens from /api/cli/auth.
      flows:
        authorizationCode:
          authorizationUrl: https://intentdocs.com/api/oauth/authorize
          tokenUrl: https://intentdocs.com/api/oauth/token
          scopes:
            read:projects: Read project metadata and story maps
            write:projects: Create and modify projects
            read:maps: Read story map data, stories, and criteria
            write:maps: Modify stories, log decisions, and report progress
            read:specs: Read generated specifications and build orders
            write:specs: Generate and update specifications
    clerkAuth:
      type: apiKey
      in: cookie
      name: __session
      description: Clerk session cookie (browser auth only)
x-refined-from:
- openapi.json
- intentdocs-com-openapi.json