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

# Create a custom API provider

> Creates one BYOK provider and optionally up to 50 actions atomically. Requires an enterprise workspace with Custom APIs enabled, the workspace owner, credentials:manage and catalog:write, plus MFA or passkey step-up completed in the last ten minutes. Locus validates the upstream URL against SSRF controls, encrypts the credential, validates every JSON Schema and example, and never returns the raw credential.



## OpenAPI

````yaml /api-reference/openapi.json post /credits/custom-endpoints
openapi: 3.1.0
info:
  title: Locus Pro API
  description: >-
    Production is live at https://api.paywithlocus.com/api. Stage remains
    available for evaluation and integration testing at
    https://api.stage.paywithlocus.com/api; credentials, balances, and tenant
    data are isolated by environment. Embedded prepaid credits over the Locus
    pay-per-use catalog. Money and top-up amounts use exact decimal strings (up
    to 6dp). Every burn requires an Idempotency-Key header. Management routes
    accept a tenant secret key or authorized dashboard session as shown per
    operation. Widget routes accept an end-user JWT alone; when a publishable
    key is present it must belong to the JWT's tenant. MCP uses OAuth 2.1
    Authorization Code with PKCE by default and also accepts the explicitly
    documented tenant secret key, end-user JWT, or scoped agent connection
    compatibility credentials. Burns accept the execution credentials shown per
    operation. Publishable keys never authorize management or burns by
    themselves.
  version: 0.6.0
servers:
  - url: https://api.paywithlocus.com/api
    description: Production
  - url: https://api.stage.paywithlocus.com/api
    description: Stage — evaluation and integration testing
security:
  - secretKey: []
tags:
  - name: Authentication
    description: Email-verified self-serve account creation and dashboard identity
  - name: Tenants
    description: Tenant profile, keys, and settings (dashboard session or secret key)
  - name: Workspace members
    description: Invite-only human workspace membership and role administration
  - name: Catalog
    description: Enable/disable APIs and set markups
  - name: Custom APIs
    description: >-
      Available when enabled for the workspace. Enterprise BYOK providers and
      schema-backed custom actions
  - name: End users
    description: End-user accounts, tokens, and allocations
  - name: Top-ups
    description: Locus-hosted checkout top-ups and quotes
  - name: Ledger
    description: Burn/top-up history and earnings
  - name: Webhooks
    description: Signed events, delivery inspection, and replay
  - name: Burn
    description: Metered pay-per-use calls
  - name: Travel routing
    description: >-
      Available when enabled for the workspace. Multi-provider flight search,
      no-dispatch planning, and feedback
  - name: MCP
    description: Stateless Streamable HTTP transport and MCP tool-result contracts
  - name: Okibi Identity
    description: >-
      Available when enabled for the workspace. Okibi identity verification and
      scoped native CLI credential bootstrap
  - name: Widget
    description: End-user JWT surface; a matching publishable key is optional
  - name: Agent-native onboarding
    description: >-
      Self-registration, human Stripe funding handoff, and restricted account
      setup for headless agents
  - name: Agent connections
    description: Scoped, expiring, revocable credentials for agent execution
  - name: Capability routing
    description: Outcome-level web search and research across eligible catalog providers
paths:
  /credits/custom-endpoints:
    post:
      tags:
        - Custom APIs
      summary: Create a custom API provider
      description: >-
        Creates one BYOK provider and optionally up to 50 actions atomically.
        Requires an enterprise workspace with Custom APIs enabled, the workspace
        owner, credentials:manage and catalog:write, plus MFA or passkey step-up
        completed in the last ten minutes. Locus validates the upstream URL
        against SSRF controls, encrypts the credential, validates every JSON
        Schema and example, and never returns the raw credential.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomProviderCreateRequest'
      responses:
        '201':
          description: Provider and any supplied actions created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomProviderResponse'
        '400':
          description: >-
            Invalid URL, authentication, traffic policy, schema, example, route,
            or pricing
        '403':
          description: >-
            Feature, enterprise plan, owner, scope, or recent step-up
            requirement not met
        '409':
          description: That provider slug is already in use in this workspace
      security:
        - dashboardSession: []
components:
  schemas:
    CustomProviderCreateRequest:
      type: object
      additionalProperties: false
      required:
        - slug
        - name
        - baseUrl
        - auth
      properties:
        slug:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$
          description: Stable provider name. The public catalog name is custom-{slug}.
        name:
          type: string
          minLength: 1
          maxLength: 80
        description:
          type: string
          maxLength: 500
        baseUrl:
          type: string
          format: uri
          maxLength: 2048
          description: >-
            HTTPS upstream origin validated against SSRF and private-network
            controls.
        auth:
          allOf:
            - $ref: '#/components/schemas/CustomAuthInput'
            - if:
                properties:
                  type:
                    enum:
                      - bearer
                      - header
                      - query
                required:
                  - type
              then:
                required:
                  - credential
        traffic:
          $ref: '#/components/schemas/CustomTrafficPolicy'
        endpoint:
          $ref: '#/components/schemas/CustomEndpointCreateRequest'
        endpoints:
          type: array
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/CustomEndpointCreateRequest'
          description: >-
            Use endpoint or endpoints, never both. Slugs must be unique within
            the request.
      not:
        required:
          - endpoint
          - endpoints
    CustomProviderResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - provider
      properties:
        success:
          const: true
        provider:
          $ref: '#/components/schemas/CustomProvider'
    CustomAuthInput:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - bearer
            - header
            - query
            - none
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: >-
            Required for header and query authentication; must be a valid HTTP
            field name.
          pattern: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$
        prefix:
          type: string
          maxLength: 80
          description: >-
            Optional value prefix for header or query authentication. Bearer
            authentication always uses 'Bearer '.
        credential:
          type: string
          minLength: 1
          maxLength: 4096
          writeOnly: true
          description: >-
            Required when creating a bearer, header, or query provider. Omit
            during an update to retain the encrypted credential. Never returned.
            At most 4,096 bytes of UTF-8.
      description: >-
        For type=none, omit credential. For type=header or type=query, supply
        name.
      allOf:
        - if:
            properties:
              type:
                enum:
                  - header
                  - query
            required:
              - type
          then:
            required:
              - name
        - if:
            properties:
              type:
                const: none
            required:
              - type
          then:
            not:
              required:
                - credential
    CustomTrafficPolicy:
      type: object
      additionalProperties: false
      required:
        - requestsPerMinute
        - maxConcurrency
        - timeoutSeconds
        - circuitBreaker
      properties:
        requestsPerMinute:
          type: integer
          minimum: 1
          maximum: 60000
          description: Must not exceed the platform-wide 60,000 request-per-minute ceiling.
        maxConcurrency:
          type: integer
          minimum: 1
          maximum: 1000
        timeoutSeconds:
          type: integer
          minimum: 1
          maximum: 120
        circuitBreaker:
          $ref: '#/components/schemas/CustomCircuitBreakerPolicy'
    CustomEndpointCreateRequest:
      type: object
      additionalProperties: false
      required:
        - slug
        - name
        - description
        - method
        - path
        - inputSchema
        - inputExample
        - providerCostUsdc
        - markupBps
        - flatMarkupUsdc
      properties:
        slug:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$
          description: Stable 3–64 character action name.
        name:
          type: string
          minLength: 1
          maxLength: 80
        description:
          type: string
          minLength: 1
          maxLength: 500
        method:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
        path:
          type: string
          minLength: 1
          maxLength: 1024
          description: >-
            Upstream path. Placeholders must reference required scalar
            properties from inputSchema.
        inputSchema:
          type: object
          additionalProperties: true
          description: >-
            Compilable JSON Schema, at most 64 KiB and 32 levels deep, whose
            root type is object. Top-level transport-control names are reserved.
        inputExample:
          type: object
          additionalProperties: true
          description: Executable example that must satisfy inputSchema.
        outputSchema:
          oneOf:
            - type: object
              additionalProperties: true
            - type: 'null'
          description: Optional JSON Schema, at most 64 KiB and 32 levels deep.
        outputExample:
          description: >-
            Optional example that must satisfy outputSchema when both are
            provided.
        providerCostUsdc:
          oneOf:
            - $ref: '#/components/schemas/DecimalString'
            - type: number
              minimum: 0
          description: Upstream provider cost in USD, rounded up to six decimal places.
        markupBps:
          type: integer
          minimum: 0
          maximum: 100000
          description: Percentage markup, also limited by the workspace's effective cap.
        flatMarkupUsdc:
          oneOf:
            - $ref: '#/components/schemas/DecimalString'
            - type: number
              minimum: 0
          description: Flat USD markup, also limited by the workspace's effective cap.
        enabled:
          type: boolean
          default: false
          description: Enabled actions must have a positive end-user price.
    CustomProvider:
      type: object
      additionalProperties: false
      required:
        - id
        - slug
        - publicProvider
        - name
        - description
        - baseUrl
        - auth
        - traffic
        - endpoints
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        publicProvider:
          type: string
          pattern: ^custom-
          description: >-
            Provider name used in catalog discovery and
            /wrapped/credits/{provider}/{endpoint}.
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        baseUrl:
          type:
            - string
            - 'null'
          format: uri
          description: Null when upstream configuration is redacted for this caller.
        auth:
          $ref: '#/components/schemas/CustomAuthView'
        traffic:
          $ref: '#/components/schemas/CustomTrafficPolicy'
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/CustomEndpoint'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CustomCircuitBreakerPolicy:
      type: object
      additionalProperties: false
      required:
        - failureThreshold
        - windowSeconds
        - cooldownSeconds
      properties:
        failureThreshold:
          type: integer
          minimum: 2
          maximum: 100
        windowSeconds:
          type: integer
          minimum: 1
          maximum: 600
        cooldownSeconds:
          type: integer
          minimum: 1
          maximum: 3600
    DecimalString:
      type: string
      pattern: ^\d+(?:\.\d{1,6})?$
      description: >-
        Non-negative exact decimal string with at most six fractional digits.
        Endpoint-specific positivity and amount limits still apply.
    CustomAuthView:
      type: object
      additionalProperties: false
      required:
        - type
        - name
        - prefix
        - configured
        - hint
        - version
        - updatedAt
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - bearer
            - header
            - query
            - none
            - null
          description: Null when upstream configuration is redacted for this caller.
        name:
          type:
            - string
            - 'null'
        prefix:
          type:
            - string
            - 'null'
        configured:
          type: boolean
        hint:
          type:
            - string
            - 'null'
          description: >-
            Non-secret credential hint for an authorized owner; never the
            credential itself.
        version:
          type: integer
          minimum: 0
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
    CustomEndpoint:
      type: object
      additionalProperties: false
      required:
        - id
        - slug
        - publicSlug
        - name
        - description
        - method
        - path
        - inputSchema
        - inputExample
        - outputSchema
        - outputExample
        - providerCostUsdc
        - markupBps
        - flatMarkupUsdc
        - endUserPriceUsdc
        - enabled
        - pricingRevision
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        publicSlug:
          type: string
          pattern: ^custom-[^/]+/[^/]+$
          description: Catalog and execution identity.
        name:
          type: string
        description:
          type: string
        method:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
        path:
          type: string
        inputSchema:
          type: object
          additionalProperties: true
        inputExample:
          type: object
          additionalProperties: true
        outputSchema:
          oneOf:
            - type: object
              additionalProperties: true
            - type: 'null'
        outputExample: {}
        providerCostUsdc:
          $ref: '#/components/schemas/DecimalString'
        markupBps:
          type: integer
          minimum: 0
        flatMarkupUsdc:
          $ref: '#/components/schemas/DecimalString'
        endUserPriceUsdc:
          $ref: '#/components/schemas/DecimalString'
        enabled:
          type: boolean
        pricingRevision:
          type: integer
          minimum: 0
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      description: Tenant secret key (lcr_…). Server-side only.
    dashboardSession:
      type: http
      scheme: bearer
      description: Locus Pro dashboard session (Cognito).

````