AgentaOS Businesses API

openapi: 3.2.0
info:
  title: Agentaos Ai Businesses API
  version: 1.0.0
  contact:
    name: AgentaOS
    url: https://agentaos.ai
  license:
    name: Proprietary
    url: https://agentaos.ai
  description: 'Operations tagged Businesses across 2 of this provider''s published API definitions: agentaos-ai-openapi.json, openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.agentaos.ai/api/v1
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Businesses
  description: 'For platforms: the businesses you manage, a client''s business or another app of your own company. To act as one of them on any other endpoint, send its id in the `AgentaOS-Account` header. Every field on this resource is camelCase on the wire.'
paths:
  /gateway/businesses:
    get:
      tags:
      - Businesses
      operationId: listBusinesses
      summary: List businesses
      description: 'Every business you manage, with its status and your share. Not paginated: returns a plain array. The platform is always the caller''s own account; an owner or admin of it.'
      responses:
        '200':
          description: Every business you manage.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Business'
              examples:
                default:
                  $ref: '#/components/examples/BusinessListExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BusinessForbidden'
    post:
      tags:
      - Businesses
      operationId: createBusiness
      summary: Create a business
      description: 'Add a business you manage. It starts in test mode and goes live after its own verification. With `clientEmail`, your client is invited as its admin, and the invitation expires after 7 days. We email the invitation, or with `sendInvitationEmail: false` we send nothing and you send `inviteUrl` yourself (white-label).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessCreateRequest'
            example:
              name: ClientCo
              country: DE
              clientEmail: founder@example.com
              sendInvitationEmail: false
      responses:
        '201':
          description: The business was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedBusiness'
        '400':
          description: A field is missing or invalid, for example a country that is not a two-letter code or a name that is an email. `message` lists every problem; `errors` names the field of each.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 400
                message:
                - Country must be a two-letter ISO code.
                error: Bad Request
                errors:
                - field: country
                  message: Country must be a two-letter ISO code.
                timestamp: '2026-09-28T12:00:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 'You are not an owner or admin of the platform, or you sent `clientEmail` as an admin: only an owner of your platform may invite the client.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                owner_only:
                  value:
                    statusCode: 403
                    message: Only an owner of your platform can invite the client as admin.
                    timestamp: '2026-09-28T12:00:00.000Z'
        '409':
          description: The caller is itself a business managed by a platform. A managed business cannot manage businesses of its own.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 409
                code: one_level
                message: A business you manage cannot manage businesses of its own.
                timestamp: '2026-09-28T12:00:00.000Z'
    servers:
    - url: https://api.agentaos.ai/api/v1
      description: Production
  /gateway/businesses/{id}:
    get:
      tags:
      - Businesses
      operationId: retrieveBusiness
      summary: Retrieve a business
      description: One business you manage, the same shape as a row of the list. A business you do not manage and an id that does not exist get the same `403`, so the response never confirms an id.
      parameters:
      - $ref: '#/components/parameters/BusinessId'
      responses:
        '200':
          description: The business.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Business'
              examples:
                default:
                  $ref: '#/components/examples/BusinessExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BusinessForbidden'
    servers:
    - url: https://api.agentaos.ai/api/v1
      description: Production
  /gateway/businesses/{id}/invitation:
    post:
      tags:
      - Businesses
      operationId: resendBusinessInvitation
      summary: Resend the invitation
      description: 'Send your client''s invitation again, to the person last invited. It is a new link that expires after 7 days: the old one stops working. Refused with `409 client_joined` once your client has joined the business.'
      parameters:
      - $ref: '#/components/parameters/BusinessId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResendInvitationRequest'
            example:
              sendInvitationEmail: false
      responses:
        '201':
          description: A new invitation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessInvitation'
              example:
                inviteToken: b7e4c1d9a2f3…
                inviteUrl: https://app.agentaos.ai/invite/b7e4c1d9a2f3…
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 'A business you do not manage, or an id that does not exist (`You cannot act as this business.`). Also returned to an admin of the platform: only an owner may invite the client.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_yours:
                  value:
                    statusCode: 403
                    message: You cannot act as this business.
                    timestamp: '2026-09-28T12:00:00.000Z'
                owner_only:
                  value:
                    statusCode: 403
                    message: Only an owner of your platform can invite the client as admin.
                    timestamp: '2026-09-28T12:00:00.000Z'
        '409':
          $ref: '#/components/responses/ClientJoined'
    delete:
      tags:
      - Businesses
      operationId: revokeBusinessInvitation
      summary: Revoke the invitation
      description: Withdraw your client's open invitation. Its link stops working. Refused with `409 client_joined` once your client has joined the business.
      parameters:
      - $ref: '#/components/parameters/BusinessId'
      responses:
        '204':
          description: The invitation was withdrawn. No body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BusinessForbidden'
        '409':
          $ref: '#/components/responses/ClientJoined'
    servers:
    - url: https://api.agentaos.ai/api/v1
      description: Production
  /gateway/businesses/{id}/verification-link:
    post:
      tags:
      - Businesses
      operationId: createBusinessVerificationLink
      summary: Create a verification link
      description: 'The identity check link for your client. You send it; only your client can complete it. Needs a live key: a test key gets `403 live_key_required`. While a check is open, calling again returns the same check. `url` is `null` when the client is already verified. For another app of your own company it returns `409 identity_from_company`: its identity check is your company''s.'
      parameters:
      - $ref: '#/components/parameters/BusinessId'
      responses:
        '201':
          description: The link, or `null` when already verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationLink'
              example:
                url: https://…
                status: Not Started
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: A business you do not manage (`You cannot act as this business.`), or a test key (`live_key_required`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_yours:
                  value:
                    statusCode: 403
                    message: You cannot act as this business.
                    timestamp: '2026-09-28T12:00:00.000Z'
                live_key_required:
                  value:
                    statusCode: 403
                    code: live_key_required
                    message: 'This needs a live API key: it changes real money, live settings or a real identity check. This is a test key.'
                    timestamp: '2026-09-28T12:00:00.000Z'
        '409':
          description: 'Another app of your own company: its identity check is your company''s.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 409
                code: identity_from_company
                message: This business is another app of your company. Its identity check is your company’s.
                timestamp: '2026-09-28T12:00:00.000Z'
    servers:
    - url: https://api.agentaos.ai/api/v1
      description: Production
components:
  schemas:
    BusinessInvitation:
      type: object
      properties:
        inviteToken:
          type: string
        inviteUrl:
          type: string
          description: The new link to send. The old one stops working.
      required:
      - inviteToken
      - inviteUrl
    ResendInvitationRequest:
      type: object
      properties:
        sendInvitationEmail:
          type: boolean
          default: true
          description: '`false`: a new link only, no email.'
    CreatedBusiness:
      type: object
      properties:
        business:
          $ref: '#/components/schemas/Business'
        inviteToken:
          type:
          - string
          - 'null'
          description: The invitation token, or null without `clientEmail`.
        inviteUrl:
          type:
          - string
          - 'null'
          description: The link your client opens to accept, or null without `clientEmail`. Ready to send.
      required:
      - business
      - inviteToken
      - inviteUrl
    Business:
      type: object
      description: 'A business you manage: a client''s business, or another app of your own company. Every field is camelCase on the wire.'
      properties:
        id:
          type: string
          format: uuid
          description: Business UUID. Send it in `AgentaOS-Account` to act as the business.
        name:
          type: string
          description: The name buyers see.
        country:
          type:
          - string
          - 'null'
          description: ISO 3166-1 alpha-2.
        status:
          type: string
          enum:
          - test_only
          - in_review
          - changes_needed
          - on_hold
          - rejected
          - live
          description: Where the business stands. `live` = verified. A bank account is needed before the first payout, not for this status. `changes_needed` = we asked the business for a change.
        platformOrgId:
          type: string
          format: uuid
          description: 'Your own id: the platform that manages it.'
        createdAt:
          type: string
          format: date-time
        platformFee:
          type: object
          description: 'Your share of its new sales, set in the dashboard: basis points of the price before VAT (`1000` = 10%) plus a fixed amount in minor units.'
          properties:
            bps:
              type: integer
            fixedMinor:
              type: integer
            fixedDisplay:
              type: string
              description: 'The fixed part as money, in the currency of this month''s fees, else euros: `€0.30`.'
          required:
          - bps
          - fixedMinor
          - fixedDisplay
        sameLegalEntity:
          type: boolean
          description: '`true` for another app of your own company: verified and priced with you, no share, no identity check of its own.'
        feesThisMonth:
          type: array
          description: Your share of its live sales this month, per currency. `feesDisplay` is ready to show.
          items:
            type: object
            properties:
              currency:
                type: string
              feesMinor:
                type: integer
              feesDisplay:
                type: string
            required:
            - currency
            - feesMinor
            - feesDisplay
        invitedEmail:
          type:
          - string
          - 'null'
          description: Who an open invitation is waiting on, or null.
        identityVerified:
          type: boolean
          description: 'The identity check is done: its own, or your company''s for another app of your own company.'
      required:
      - id
      - name
      - country
      - status
      - platformOrgId
      - createdAt
      - platformFee
      - sameLegalEntity
      - feesThisMonth
      - invitedEmail
      - identityVerified
    BusinessCreateRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 100
          description: The name buyers see. A brand, not an email.
        country:
          type: string
          pattern: ^[A-Z]{2}$
          description: Where it is registered, ISO 3166-1 alpha-2, upper case.
        clientEmail:
          type: string
          format: email
          description: Invite your client as its admin. Leave it out to run the business yourself. Only an owner of your platform may invite.
        sameLegalEntity:
          type: boolean
          default: false
          description: '`true` for another app of your own company.'
        sendInvitationEmail:
          type: boolean
          default: true
          description: '`false`: we send no email; you send `inviteUrl` yourself (white-label).'
      required:
      - name
      - country
    VerificationLink:
      type: object
      properties:
        url:
          type:
          - string
          - 'null'
          description: The identity check link to send your client, or null when already verified.
        status:
          type: string
          description: 'Where the identity check stands. These are the check''s own states, not a business status: `Not Started`, `In Progress`, `Awaiting User`, `In Review`, `Approved`, `Declined`, `Resubmitted`, `Expired`, `Kyc Expired` or `Abandoned`. `Approved` means the check is done.'
      required:
      - url
      - status
    Error:
      type: object
      description: Every non-2xx response is JSON in this shape. Every response (success or error) also carries an `x-request-id` response header; send that header on your request to have your own id echoed back, otherwise the server mints one. On errors the same id is repeated in the `requestId` body field.
      properties:
        statusCode:
          type: integer
          description: Same as the HTTP status code.
        code:
          type: string
          description: 'Present on some refusals: a stable machine-readable reason, e.g. `live_key_required`.'
        message:
          description: Human-readable. A validation failure (400) returns an array of per-field messages instead of one string.
          anyOf:
          - type: string
          - type: array
            items:
              type: string
        errors:
          type: array
          description: 'Present on 400 validation failures: one entry per invalid field. The flat human-readable strings stay in `message` for back-compat; this is the machine-readable, per-field view.'
          items:
            type: object
            properties:
              field:
                type: string
                description: Name of the invalid field, dot-notated for nested properties (e.g. `checkoutFields.0.type`).
              message:
                type: string
                description: Validation messages for that field, joined with `, `.
            required:
            - field
            - message
        requestId:
          type: string
          description: Correlation id, identical to the `x-request-id` response header. Include it when contacting support. On success it is available on the header only, not the body.
        timestamp:
          type: string
          format: date-time
      required:
      - statusCode
      - message
      - timestamp
  responses:
    BusinessForbidden:
      description: 'A business you do not manage, or an id that does not exist: the same answer for both, so the response never confirms an id. Also returned when the caller is not an owner or admin of the platform.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 403
            message: You cannot act as this business.
            timestamp: '2026-09-28T12:00:00.000Z'
    Unauthorized:
      description: Missing or invalid `x-api-key`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 401
            message: Invalid API key
            timestamp: '2026-08-06T12:00:00.000Z'
    ClientJoined:
      description: 'Your client has already joined this business: its invitations are now theirs to manage.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 409
            code: client_joined
            message: Your client has already joined this business.
            timestamp: '2026-09-28T12:00:00.000Z'
  examples:
    BusinessExample:
      value:
        id: 5b1f0c2e-8a4d-4c7b-9e21-3f6a7d8c9b10
        name: ClientCo
        country: DE
        status: in_review
        platformOrgId: 0e6d2c1a-3b4f-4a5e-8c7d-9f1a2b3c4d5e
        createdAt: '2026-09-28T10:00:00.000Z'
        platformFee:
          bps: 1000
          fixedMinor: 50
          fixedDisplay: €0.50
        sameLegalEntity: false
        feesThisMonth:
        - currency: EUR
          feesMinor: 1250
          feesDisplay: €12.50
        invitedEmail: founder@example.com
        identityVerified: false
    BusinessListExample:
      value:
      - id: 5b1f0c2e-8a4d-4c7b-9e21-3f6a7d8c9b10
        name: ClientCo
        country: DE
        status: in_review
        platformOrgId: 0e6d2c1a-3b4f-4a5e-8c7d-9f1a2b3c4d5e
        createdAt: '2026-09-28T10:00:00.000Z'
        platformFee:
          bps: 1000
          fixedMinor: 50
          fixedDisplay: €0.50
        sameLegalEntity: false
        feesThisMonth:
        - currency: EUR
          feesMinor: 1250
          feesDisplay: €12.50
        invitedEmail: founder@example.com
        identityVerified: false
  parameters:
    BusinessId:
      name: id
      in: path
      required: true
      description: The business UUID.
      schema:
        type: string
        format: uuid
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Your secret key, from app.agentaos.ai -> Settings -> Developers -> API Keys. The key''s prefix is both its identity and its environment: `sk_test_...` (sandbox, free, no verification) or `sk_live_...` (real money, requires business verification). A missing or invalid key returns 401.'
x-refined-from:
- agentaos-ai-openapi.json
- openapi.json