Hlix Coder Accounts API

openapi: 3.2.0
info:
  description: Explore the Hlix API for projects, agent teams, and delivery workflows. Authenticate with `x-api-key` and select a Workspace with `X-Organization-Id`. Session-only operations require a signed-in user session. Authentication setup.
  title: reference Coder Accounts API
  version: 1.0.0
servers:
- url: https://server.hlix.ai
  description: API server
security:
- apiKey: []
- sessionCookie: []
tags:
- description: Connected subscriptions and custom API keys for native coders.
  name: coder-accounts
paths:
  /v1/api/coder-accounts:
    get:
      operationId: listCoderAccounts
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/CoderAccount'
                type: array
          description: Members see their own and shared accounts; owners/admins see all. Credentials are never returned.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner's consent.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: List safe coder accounts
      tags:
      - coder-accounts
    post:
      operationId: createCoderAccount
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCoderAccount'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoderAccount'
          description: Connected account. Subscription defaults to private ownership.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: Invalid body or credential, or unsupported account operation.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner's consent.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The session is already connected or the account is running a task.
      summary: Import a subscription credential or custom API key
      tags:
      - coder-accounts
  /v1/api/coder-accounts/connect:
    post:
      operationId: startCoderAccountConnect
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartCoderConnect'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoderConnect'
          description: Provider authorization instructions. Expires after ten minutes.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: Invalid body or credential, or unsupported account operation.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner's consent.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such account visible in this workspace.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The session is already connected or the account is running a task.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Provider unavailable.
      summary: Start subscription sign-in
      tags:
      - coder-accounts
  /v1/api/coder-accounts/connect/{sessionId}:
    delete:
      operationId: cancelCoderAccountConnect
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedAck'
          description: Cancelled.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner's consent.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such account visible in this workspace.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The session is already connected or the account is running a task.
      summary: Cancel subscription sign-in
      tags:
      - coder-accounts
  /v1/api/coder-accounts/connect/{sessionId}/complete:
    post:
      operationId: completeCoderAccountConnect
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteCoderConnect'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoderConnectResult'
          description: Pending authorization or connected account ID. Never returns credentials.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: Invalid body or credential, or unsupported account operation.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner's consent.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such account visible in this workspace.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The session is already connected or the account is running a task.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Provider unavailable.
      summary: Finish subscription sign-in or poll device authorization
      tags:
      - coder-accounts
  /v1/api/coder-accounts/{id}:
    delete:
      operationId: deleteCoderAccount
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedAck'
          description: Removed. A named pin will remain unavailable until explicitly changed.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner's consent.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such account visible in this workspace.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The session is already connected or the account is running a task.
      summary: Remove an account and its credential
      tags:
      - coder-accounts
    patch:
      operationId: updateCoderAccount
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchCoderAccount'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoderAccount'
          description: Updated account.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: Invalid body or credential, or unsupported account operation.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner's consent.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such account visible in this workspace.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The session is already connected or the account is running a task.
      summary: Rename, share or enable an account
      tags:
      - coder-accounts
  /v1/api/coder-accounts/{id}/credential:
    put:
      operationId: reconnectCoderAccount
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReconnectCoderAccount'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoderAccount'
          description: Reconnected account with the same coder and kind.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: Invalid body or credential, or unsupported account operation.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner's consent.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such account visible in this workspace.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The session is already connected or the account is running a task.
      summary: Replace an account credential
      tags:
      - coder-accounts
  /v1/api/coder-accounts/{id}/models:
    get:
      operationId: getCoderAccountModels
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoderAccountModelCatalog'
          description: Advertised models, not proof of entitlement. Never probes the provider.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner's consent.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such account visible in this workspace.
      summary: Read cached models advertised by an account
      tags:
      - coder-accounts
  /v1/api/coder-accounts/{id}/models/refresh:
    post:
      operationId: refreshCoderAccountModels
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoderAccountModelCatalog'
          description: Cached API model list. Subscription menus come from normal native sessions.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: Invalid body or credential, or unsupported account operation.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner's consent.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such account visible in this workspace.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The session is already connected or the account is running a task.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Provider model list unavailable.
      summary: Refresh an API account's advertised models
      tags:
      - coder-accounts
  /v1/api/coder-accounts/{id}/test:
    post:
      operationId: testCoderAccount
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoderAccountProbe'
          description: API key check succeeded.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: Invalid body or credential, or unsupported account operation.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner's consent.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such account visible in this workspace.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoderAccountProbe'
          description: Provider check failed; safe details only.
      summary: Check a Claude or Codex API key
      tags:
      - coder-accounts
components:
  schemas:
    ApiError:
      additionalProperties: {}
      properties:
        error:
          type: string
      required:
      - error
      type: object
    CoderConnectResult:
      properties:
        accountId:
          type: string
        status:
          enum:
          - pending
          - connected
          type: string
      required:
      - status
      type: object
    CoderConnect:
      properties:
        expiresAt:
          type: string
        id:
          type: string
        interval:
          type: number
        method:
          enum:
          - device
          - code
          - callback
          type: string
        url:
          type: string
        userCode:
          type: string
      required:
      - id
      - url
      - expiresAt
      - interval
      - method
      type: object
    CoderAccount:
      properties:
        baseUrl:
          type:
          - string
          - 'null'
        coder:
          enum:
          - claude-code
          - codex
          type: string
        createdAt:
          type: string
        enabled:
          type: boolean
        expiresAt:
          type:
          - string
          - 'null'
        hint:
          type:
          - string
          - 'null'
        id:
          type: string
        inUse:
          type: boolean
        kind:
          enum:
          - subscription
          - api_key
          type: string
        label:
          type: string
        lastUsedAt:
          type:
          - string
          - 'null'
        limitedUntil:
          type:
          - string
          - 'null'
        ownerUserId:
          type:
          - string
          - 'null'
        shared:
          type: boolean
        status:
          enum:
          - active
          - needs_reconnect
          type: string
        updatedAt:
          type: string
        usage:
          anyOf:
          - properties:
              capturedAt:
                type: string
              windows:
                items:
                  properties:
                    resetsAt:
                      type: string
                    usedPercent:
                      type: number
                    window:
                      type: string
                  required:
                  - window
                  - usedPercent
                  type: object
                type: array
            required:
            - windows
            - capturedAt
            type: object
          - type: 'null'
      required:
      - id
      - coder
      - kind
      - label
      - hint
      - baseUrl
      - ownerUserId
      - shared
      - enabled
      - status
      - limitedUntil
      - expiresAt
      - lastUsedAt
      - inUse
      - usage
      - createdAt
      - updatedAt
      type: object
    CoderAccountProbe:
      properties:
        detail:
          type: string
        ok:
          type: boolean
        status:
          type: number
      required:
      - ok
      - status
      type: object
    ReconnectCoderAccount:
      additionalProperties: false
      properties:
        baseUrl:
          anyOf:
          - format: uri
            type: string
          - type: 'null'
        credential:
          maxLength: 20000
          minLength: 1
          type: string
      required:
      - credential
      type: object
    PatchCoderAccount:
      additionalProperties: false
      properties:
        enabled:
          type: boolean
        label:
          maxLength: 80
          minLength: 1
          type: string
        shared:
          type: boolean
      type: object
    StartCoderConnect:
      additionalProperties: false
      properties:
        accountId:
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          type: string
        callbackPort:
          maximum: 65535
          minimum: 1024
          type: integer
        coder:
          enum:
          - claude-code
          - codex
          type: string
        label:
          maxLength: 80
          minLength: 1
          type: string
        shared:
          default: false
          type: boolean
      required:
      - coder
      - label
      type: object
    DeletedAck:
      properties:
        ok:
          const: true
          type: boolean
      required:
      - ok
      type: object
    ValidationError:
      properties:
        error:
          properties:
            message:
              type: string
            name:
              type: string
          required:
          - name
          - message
          type: object
        success:
          const: false
          type: boolean
      required:
      - success
      - error
      type: object
    CompleteCoderConnect:
      additionalProperties: false
      properties:
        code:
          maxLength: 4096
          minLength: 1
          type: string
      type: object
    CreateCoderAccount:
      additionalProperties: false
      properties:
        baseUrl:
          format: uri
          type: string
        coder:
          enum:
          - claude-code
          - codex
          type: string
        credential:
          maxLength: 20000
          minLength: 1
          type: string
        kind:
          enum:
          - subscription
          - api_key
          type: string
        label:
          maxLength: 80
          minLength: 1
          type: string
        shared:
          type: boolean
      required:
      - coder
      - kind
      - label
      - credential
      type: object
    CoderAccountModelCatalog:
      properties:
        capturedAt:
          type:
          - string
          - 'null'
        models:
          items:
            additionalProperties: false
            properties:
              id:
                maxLength: 200
                minLength: 1
                pattern: ^[\w./:~@+-]+$
                type: string
              name:
                maxLength: 256
                minLength: 1
                pattern: ^[^\x00-\x1f\x7f]+$
                type: string
            required:
            - id
            - name
            type: object
          maxItems: 1000
          type: array
        source:
          anyOf:
          - enum:
            - native
            - api
            type: string
          - type: 'null'
        status:
          enum:
          - available
          - unknown
          - stale
          type: string
      required:
      - models
      - status
      - source
      - capturedAt
      type: object
  parameters:
    OrganizationId:
      description: The workspace (organization) to act in. Omitted, the session's active organization is used.
      in: header
      name: X-Organization-Id
      required: false
      schema:
        type: string
      example: YOUR_WORKSPACE_ID
  securitySchemes:
    apiKey:
      description: An API key issued through `/v1/api/auth/api-key/*`. Browser clients can use their session cookie instead.
      in: header
      name: x-api-key
      type: apiKey
    sessionCookie:
      description: The complete session Cookie header issued by sign-in at the selected API host. Cookie names vary by hosting region and environment; preserve the issued name and value. Browsers send these HTTP-only cookies automatically. Session-only operations require this user session and do not accept an API key.
      in: header
      name: Cookie
      type: apiKey