intentdocs-com CLI API

openapi: 3.2.0
info:
  title: Intentdocs Com CLI 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 CLI 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: CLI
  description: Authentication and project discovery for CLI tools like intentdocs-cli
paths:
  /api/cli/auth:
    post:
      operationId: createCliAuthRequest
      tags:
      - CLI
      summary: Create CLI authentication request
      description: Start the CLI login flow by creating a pending authentication request. Returns a code that the CLI displays to the user for browser-based approval.
      responses:
        '200':
          description: Authentication request created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                properties:
                  code:
                    type: string
                    description: One-time code for CLI polling (expires in 10 minutes)
                    example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
    get:
      operationId: pollCliAuthStatus
      tags:
      - CLI
      summary: Poll CLI authentication status
      description: Check if a CLI authentication request was approved by the user in the browser. Called repeatedly by the CLI until approved or expired.
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: string
        description: The authentication code from createCliAuthRequest
      responses:
        '200':
          description: Authentication status
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    status:
                      enum:
                      - pending
                      description: Still awaiting user approval
                - type: object
                  properties:
                    status:
                      enum:
                      - expired
                      description: Request expired (10-minute window passed)
                - type: object
                  properties:
                    status:
                      enum:
                      - approved
                    token:
                      type: string
                      description: Long-lived CLI token (intent_cli_* prefix; tokens issued before the rebrand still authenticate)
                    userId:
                      type: string
                    posthogKey:
                      type:
                      - string
                      - 'null'
                    posthogHost:
                      type:
                      - string
                      - 'null'
        '400':
          description: Missing or invalid code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Authentication code not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded for polling
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: approveCliAuthRequest
      tags:
      - CLI
      summary: Approve CLI authentication request
      description: Called from the browser (authenticated via Clerk) to approve a pending CLI authentication request and generate a long-lived token.
      security:
      - clerkAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - code
              properties:
                code:
                  type: string
                  description: The authentication code to approve
      responses:
        '200':
          description: Request approved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
        '400':
          description: Invalid or expired authentication request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://intentdocs.com
      description: Production server
    - url: http://localhost:3000
      description: Development server
  /api/cli/projects:
    get:
      operationId: listCliProjects
      tags:
      - CLI
      summary: List user's projects
      description: Retrieve all projects owned by the authenticated user. Used by the CLI to discover available projects for map operations.
      security:
      - bearerAuth:
        - read:projects
      responses:
        '200':
          description: List of projects
          content:
            application/json:
              schema:
                type: object
                required:
                - projects
                properties:
                  projects:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique project identifier
                        name:
                          type: string
                          description: Project title
                        description:
                          type: string
                          description: Project problem statement
        '401':
          description: Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Failed to fetch projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://intentdocs.com
      description: Production server
    - url: http://localhost:3000
      description: Development server
  /api/cli/projects/{projectId}/maps:
    get:
      operationId: listCliProjectMaps
      tags:
      - CLI
      summary: List story maps for a project
      description: Retrieve all story maps for a specific project. Sync calls take the map id in the path and authenticate with the same CLI bearer.
      security:
      - bearerAuth:
        - read:maps
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
        description: The project ID
      responses:
        '200':
          description: List of story maps
          content:
            application/json:
              schema:
                type: object
                properties:
                  maps:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                        status:
                          type: string
                  appUrl:
                    type: string
        '401':
          description: Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Failed to fetch maps
          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
  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