Insforge Client API

openapi: 3.2.0
info:
  title: Insforge AI Admin Client API
  version: 1.0.0
  description: Model Gateway helper APIs for OpenRouter key provisioning, model discovery, and deprecated compatibility proxy routes
servers:
- url: https://api.insforge.dev
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Client
paths:
  /api/ai/chat/completion:
    post:
      summary: Generate chat completion (deprecated)
      deprecated: true
      description: Deprecated compatibility proxy. New integrations should call https://openrouter.ai/api/v1/chat/completions directly with the provisioned OpenRouter key.
      tags:
      - Client
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: Chat completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
                description: Server-sent events stream for streaming responses
        '400':
          description: Invalid request - missing model or messages
        '401':
          description: Unauthorized
        '500':
          description: Failed to get response
  /api/ai/image/generation:
    post:
      summary: Generate images (deprecated)
      deprecated: true
      description: Deprecated compatibility proxy. New integrations should use OpenRouter image-capable models directly with the provisioned OpenRouter key.
      tags:
      - Client
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerationOptions'
      responses:
        '200':
          description: Images generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  model:
                    type: string
                    description: Model used for generation
                  images:
                    type: array
                    items:
                      $ref: '#/components/schemas/OpenRouterImageMessage'
                  text:
                    type: string
                    description: Text content from multimodal models
                  count:
                    type: integer
                    description: Number of images generated
                  metadata:
                    type: object
                    properties:
                      model:
                        type: string
                      revisedPrompt:
                        type: string
                      usage:
                        $ref: '#/components/schemas/TokenUsage'
                  nextActions:
                    type: string
                    example: Images have been generated successfully. Use the returned URLs or base64 data to access them.
        '400':
          description: Invalid request - missing model or prompt
        '401':
          description: Unauthorized
        '500':
          description: Failed to generate image
  /api/ai/embeddings:
    post:
      summary: Generate embeddings (deprecated)
      deprecated: true
      description: Deprecated compatibility proxy. New integrations should call https://openrouter.ai/api/v1/embeddings directly with the provisioned OpenRouter key.
      tags:
      - Client
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingsRequest'
      responses:
        '200':
          description: Embeddings generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingsResponse'
        '400':
          description: Invalid request - missing model or input
        '401':
          description: Unauthorized
        '500':
          description: Failed to generate embeddings
  /api/auth/public-config:
    get:
      summary: Get public authentication configuration
      description: Get all public authentication configuration including OAuth providers and email auth settings (public endpoint)
      tags:
      - Client
      responses:
        '200':
          description: Public authentication configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  oAuthProviders:
                    type: array
                    items:
                      type: string
                      enum:
                      - google
                      - github
                      - discord
                      - linkedin
                      - facebook
                      - instagram
                      - tiktok
                      - apple
                      - x
                      - spotify
                      - microsoft
                  customOAuthProviders:
                    type: array
                    items:
                      type: string
                  requireEmailVerification:
                    type: boolean
                  passwordMinLength:
                    type: integer
                    minimum: 4
                    maximum: 128
                  requireNumber:
                    type: boolean
                  requireLowercase:
                    type: boolean
                  requireUppercase:
                    type: boolean
                  requireSpecialChar:
                    type: boolean
                  verifyEmailMethod:
                    type: string
                    enum:
                    - code
                    - link
                    description: Method for email verification (code = 6-digit OTP, link = magic link)
                  resetPasswordMethod:
                    type: string
                    enum:
                    - code
                    - link
                    description: Method for password reset (code = 6-digit OTP + exchange flow, link = magic link)
                  disableSignup:
                    type: boolean
                    description: When true, new user sign-ups are disabled. Existing users can still sign in.
  /api/auth/profiles/current:
    patch:
      summary: Update current user's profile
      description: Update the profile of the currently authenticated user
      tags:
      - Client
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - profile
              properties:
                profile:
                  type: object
                  additionalProperties: true
                  description: Profile data (name, avatar_url, and any custom fields)
                  properties:
                    name:
                      type: string
                    avatar_url:
                      type: string
                      format: uri
      responses:
        '200':
          description: Profile updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized - authentication required
  /api/auth/profiles/{userId}:
    get:
      summary: Get user profile by ID
      description: Get public profile information for a user by their ID (public endpoint)
      tags:
      - Client
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: User ID
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
        '400':
          description: Invalid user ID format
        '404':
          description: User not found
  /api/auth/users:
    post:
      summary: Register new user
      description: Creates a new user account
      tags:
      - Client
      parameters:
      - name: client_type
        in: query
        schema:
          type: string
          enum:
          - web
          - mobile
          - desktop
          - server
          default: web
        description: 'Client type determines how refresh tokens are returned:

          - web: Refresh token stored in httpOnly cookie, csrfToken returned in response

          - mobile/desktop/server: refreshToken returned directly in response body

          '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - password
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                password:
                  type: string
                  description: Password meeting configured requirements (check /api/auth/email/config for current requirements)
                  example: securepassword123
                name:
                  type: string
                  example: John Doe
                redirectTo:
                  type: string
                  format: uri
                  description: 'Used for link-based email verification. The email link always opens an InsForge backend endpoint first; after the token is verified, InsForge redirects the browser to this URL. This URL must be included in allowedRedirectUrls. Recommended: use your app''s sign-in page.'
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/UserResponse'
                  accessToken:
                    type:
                    - string
                    - 'null'
                    description: JWT authentication token (null if email verification required)
                  csrfToken:
                    type:
                    - string
                    - 'null'
                    description: CSRF token for use with refresh endpoint (web clients only, null if email verification required)
                  refreshToken:
                    type:
                    - string
                    - 'null'
                    description: Refresh token for mobile/desktop/server clients (null for web clients or if email verification required)
                  requireEmailVerification:
                    type: boolean
                    description: Whether email verification is required before login
        '400':
          description: Invalid request
        '403':
          description: Signups disabled — project has disabled new user registration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: AUTH_SIGNUP_DISABLED
                message: User signups are disabled for this project.
                statusCode: 403
        '409':
          description: User already exists
  /api/auth/sessions:
    post:
      summary: User login
      description: Authenticates user and returns access token. For web clients, sets httpOnly refresh token cookie. For mobile/desktop/server clients, returns refreshToken in response body.
      tags:
      - Client
      parameters:
      - name: client_type
        in: query
        schema:
          type: string
          enum:
          - web
          - mobile
          - desktop
          - server
          default: web
        description: 'Client type determines how refresh tokens are returned:

          - web: Refresh token stored in httpOnly cookie, csrfToken returned in response

          - mobile/desktop/server: refreshToken returned directly in response body

          '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/UserResponse'
                  accessToken:
                    type: string
                  csrfToken:
                    type:
                    - string
                    - 'null'
                    description: CSRF token for use with refresh endpoint (web clients only)
                  refreshToken:
                    type:
                    - string
                    - 'null'
                    description: Refresh token for mobile/desktop/server clients (null for web clients)
        '401':
          description: Invalid credentials
        '403':
          description: Email verification required
  /api/auth/refresh:
    post:
      summary: Refresh access token
      description: 'Refresh access token using refresh token.

        - Web clients: Use httpOnly refresh token cookie with X-CSRF-Token header

        - Mobile/Desktop/Server clients: Send refreshToken in request body

        '
      tags:
      - Client
      parameters:
      - name: client_type
        in: query
        schema:
          type: string
          enum:
          - web
          - mobile
          - desktop
          - server
          default: web
        description: 'Client type determines how refresh tokens are handled:

          - web: Refresh token from httpOnly cookie, requires X-CSRF-Token header

          - mobile/desktop/server: refreshToken provided in request body, new refreshToken returned in response

          '
      - name: X-CSRF-Token
        in: header
        schema:
          type: string
        description: CSRF token received from login/register response (required for web clients only)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                refreshToken:
                  type: string
                  description: Refresh token (required for mobile/desktop/server clients only)
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/UserResponse'
                  accessToken:
                    type: string
                  csrfToken:
                    type:
                    - string
                    - 'null'
                    description: New CSRF token for subsequent refresh requests (web clients only)
                  refreshToken:
                    type:
                    - string
                    - 'null'
                    description: New refresh token for mobile/desktop/server clients (must be persisted for next refresh)
        '401':
          description: No refresh token provided or user not found
        '403':
          description: Invalid CSRF token
  /api/auth/logout:
    post:
      summary: Logout user
      description: 'Logout the current client session.


        Web clients use the httpOnly refresh token cookie. If a valid web refresh cookie is present,

        the request must include the `X-CSRF-Token` header returned from login, registration, or refresh.

        Missing, expired, invalid, or wrong-session-type refresh cookies are cleared idempotently and still

        return success. Mobile, desktop, and server clients do not have server-side logout state and should

        discard their stored refresh token after this request.

        '
      tags:
      - Client
      parameters:
      - name: client_type
        in: query
        schema:
          type: string
          enum:
          - web
          - mobile
          - desktop
          - server
          default: web
        description: Client type. Web clients clear the httpOnly refresh cookie; other clients should discard their local refresh token.
      - name: X-CSRF-Token
        in: header
        schema:
          type: string
        description: CSRF token required for web clients when a valid refresh cookie is present
      responses:
        '200':
          description: Logged out successfully. Also returned when the refresh cookie is missing, expired, invalid, or the wrong session type.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '403':
          description: Invalid or missing CSRF token for a valid web refresh cookie
  /api/auth/sessions/current:
    get:
      summary: Get current session
      description: 'Returns the currently authenticated user''s basic info from the access token.

        Project admin tokens return a projectAdmin session object instead of an auth.users row.


        This endpoint does not refresh expired access tokens by itself.

        For browser apps using the TypeScript SDK, call `auth.getCurrentUser()`

        during startup. The SDK will use the httpOnly refresh cookie automatically

        when it can refresh the session. Server, mobile, and other non-browser

        clients should call `/api/auth/refresh` explicitly.

        '
      tags:
      - Client
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Current session info
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  required:
                  - user
                  additionalProperties: false
                  properties:
                    user:
                      $ref: '#/components/schemas/UserResponse'
                - type: object
                  required:
                  - projectAdmin
                  additionalProperties: false
                  properties:
                    projectAdmin:
                      $ref: '#/components/schemas/ProjectAdminResponse'
        '401':
          description: Unauthorized
  /api/auth/email/send-verification:
    post:
      summary: Send email verification (code or link based on config)
      description: Send email verification using the method configured in auth settings (verifyEmailMethod). When method is 'code', sends a 6-digit numeric code. When method is 'link', sends a browser verification link that goes through an InsForge backend endpoint first. Prevents user enumeration by returning success even if email doesn't exist.
      tags:
      - Client
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                redirectTo:
                  type: string
                  format: uri
                  description: 'Used for link-based email verification. The email link always opens an InsForge backend endpoint first; after the token is verified, InsForge redirects the browser to this URL. This URL must be included in allowedRedirectUrls. Recommended: use your app''s sign-in page.'
      responses:
        '202':
          description: Verification email sent (if email exists). Message varies based on configured method.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: If your email is registered, we have sent you a verification code/link. Please check your inbox.
        '400':
          description: Invalid request
  /api/auth/email/verify-link:
    get:
      summary: Verify email from browser link click
      description: 'Browser-oriented link verification flow.


        This endpoint is intended for users clicking verification links in email.

        It validates the token on the backend and redirects the browser to the

        stored, validated `redirectTo` URL with the verification result.


        Redirect query params:

        - Success: `insforge_status=success&insforge_type=verify_email`

        - Error: `insforge_status=error&insforge_type=verify_email&insforge_error=...`

        - `insforge_status`: `success` or `error`

        - `insforge_type`: always `verify_email`

        - `insforge_error`: present only on error, human-readable message


        Recommended handling: use your sign-in page as `redirectTo`. When the

        redirect arrives with `insforge_status=success`, show a confirmation message

        and ask the user to sign in with their email and password.

        '
      tags:
      - Client
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
        description: 64-character email verification token from the email link
      responses:
        '302':
          description: Browser redirected to the stored redirect URL
        '400':
          description: Invalid verification token or redirect target
  /api/auth/email/verify:
    post:
      summary: Verify email with code
      description: 'Verify email address with a 6-digit code.


        Successfully verified users will receive a session token.


        Browser email clicks should use `GET /api/auth/email/verify-link`.

        `POST /api/auth/email/verify` is the JSON API for 6-digit code submission.

        '
      tags:
      - Client
      parameters:
      - name: client_type
        in: query
        schema:
          type: string
          enum:
          - web
          - mobile
          - desktop
          - server
          default: web
        description: 'Client type determines how refresh tokens are returned:

          - web: Refresh token stored in httpOnly cookie, csrfToken returned in response

          - mobile/desktop/server: refreshToken returned directly in response body

          '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - otp
              properties:
                email:
                  type: string
                  format: email
                  description: User email address
                  example: user@example.com
                otp:
                  type: string
                  pattern: ^\d{6}$
                  description: 6-digit verification code
                  example: '123456'
      responses:
        '200':
          description: Email verified successfully, session created
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/UserResponse'
                  accessToken:
                    type: string
                    description: JWT authentication token
                  csrfToken:
                    type:
                    - string
                    - 'null'
                    description: CSRF token for use with refresh endpoint (web clients only)
                  refreshToken:
                    type:
                    - string
                    - 'null'
                    description: Refresh token for mobile/desktop/server clients (null for web clients)
        '400':
          description: Invalid verification code or token
        '401':
          description: Verification code/token expired or invalid
  /api/auth/email/send-reset-password:
    post:
      summary: Send password reset (code or link based on config)
      description: Send password reset email using the method configured in auth settings (resetPasswordMethod). When method is 'code', sends a 6-digit numeric code for two-step flow. When method is 'link', sends a browser reset link that goes through an InsForge backend endpoint first. Prevents user enumeration by returning success even if email doesn't exist.
      tags:
      - Client
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                redirectTo:
                  type: string
                  format: uri
                  description: 'Used for link-based password reset. The email link always opens an InsForge backend endpoint first; InsForge then redirects the browser to this URL with the reset token in the query string. This URL must be included in allowedRedirectUrls. Recommended: use your app''s dedicated reset-password page.'
      responses:
        '202':
          description: Password reset email sent (if email exists). Message varies based on configured method.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: If your email is registered, we have sent you a password reset code/link. Please check your inbox.
        '400':
          description: Invalid request
  /api/auth/email/exchange-reset-password-token:
    post:
      summary: Exchange reset password code for reset token
      description: 'Step 1 of two-step password reset flow (only used when resetPasswordMethod is ''code''):

        1. Verify the 6-digit code sent to user''s email

        2. Return a reset token that can be used to actually reset the password


        This endpoint is not used when resetPasswordMethod is ''link'', because the browser reset-link flow uses the emailed link token directly.

        '
      tags:
      - Client
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - code
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                code:
                  type: string
                  pattern: ^\d{6}$
                  description: 6-digit numeric code from email
                  example: '123456'
      responses:
        '200':
          description: Code verified successfully, reset token returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: Reset token to be used in reset-password endpoint
                  expiresAt:
                    type: string
                    format: date-time
                    description: Token expiration timestamp
        '400':
          description: Invalid request
        '401':
          description: Invalid or expired code
  /api/auth/email/reset-password-link:
    get:
      summary: Open password reset flow from browser link click
      description: 'Browser-oriented password reset link flow.


        This endpoint is intended for users clicking password reset links in email.

        It validates the token on the backend and redirects the browser to the

        stored, validated `redirectTo` URL with the reset token in the query string.


        Redirect query params:

        - Ready: `token=...&insforge_status=ready&insforge_type=reset_password`

        - Error: `insforge_status=error&insforge_type=reset_password&insforge_error=...`

        - `token`: present only when `insforge_status=ready`

        - `insforge_status`: `ready` or `error`

        - `insforge_type`: always `reset_password`

        - `insforge_error`: present only on error, human-readable message


        Your app should render the reset-password form only when `insforge_status=ready`

        and `token` is present.

        '
      tags:
      - Client
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
        description: 64-character password reset token from the email link
      responses:
        '302':
          description: Browser redirected to the stored redirect URL
        '400':
          description: Invalid reset token or redirect target
  /api/auth/email/reset-password:
    post:
      summary: Reset password with token
      description: 'Reset user password with a token. The token can be:

        - Magic link token (64-character hex token from send-reset-password when method is ''link'')

        - Reset token (from exchange-reset-password-token after code verification when method is ''code'')


        Both token types use RESET_PASSWORD purpose and are verified the same way.


        Flow summary:

        - Code method: send-reset-password → exchange-reset-password-token → reset-password (with resetToken)

        - Link method: send-reset-password → GET /api/auth/email/reset-password-link → reset-password

        '
      tags:
      - Client
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - newPassword
              - otp
              properties:
                newPassword:
                  type: string
                  description: New password meeting configured requirements
                  example: newSecurePassword123
                otp:
                  type: string
                  description: Reset token (either from magic link or from exchange-reset-password-token endpoint)
                  example: a1b2c3d4...
      responses:
        '200':
          description: Password reset successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Password reset successfully
        '400':
          description: Invalid request or password requirements not met
        '401':
          description: Verification code/token expired or invalid
  /api/auth/oauth/{provider}:
    get:
      summary: Initiate OAuth flow (PKCE)
      description: 'Generate OAuth authorization URL for any supported provider using PKCE flow.


        For mobile/desktop/server clients using PKCE:

        1. Generate code_verifier (random string, 43-128 chars)

        2. Generate code_challenge = Base64URL(SHA256(code_verifier))

        3. Call this endpoint with code_challenge

        4. After OAuth callback, use /api/auth/oauth/exchange with code_verifier

        '
      tags:
      - Client
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          enum:
          - google
          - github
          - discord
          - linkedin
          - facebook
          - instagram
          - tiktok
          - apple
          - x
          - spotify
          - microsoft
      - name: redirect_uri
        in: query
        required: true
        schema:
  

# --- truncated at 32 KB (100 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/insforge/refs/heads/main/openapi/insforge-client-api-openapi.yml