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

# Create team

> Create a new team.

Requires the `multipleIssuerAccounts` feature on your plan → `403 insufficient_permissions` without it.

**gigstack Connect:** Create teams using the `team` parameter.

Requires a plan with the "Proveedores" feature: otherwise the call answers `401` with
`You should subscribe to a plan that allows "Proveedores" feature.` (standardized envelope).




## OpenAPI

````yaml openapi.json POST /teams
openapi: 3.0.3
info:
  title: gigstack API v2
  description: >
    # gigstack API v2


    Build customer, invoice and payment integrations. Start with the
    [quickstart](https://docs.gigstack.io/quickstart), then select the [issuing
    country](https://docs.gigstack.io/concepts/shared-fields).


    ## Authentication and environments


    Use Authorization: Bearer YOUR_API_KEY. Standard live and test keys use
    https://api.gigstack.io/v2. Internal staging uses
    https://gigstack-staging-9z9nnaat.uc.gateway.dev/v2 and separate keys. Test
    mode is a data mode within an environment; a body field does not switch a
    key's mode.


    See [authentication](https://docs.gigstack.io/authentication) for key
    handling, OAuth team scope and gigstack Connect. Signup requires its
    separately documented internal credential; health probes have their own
    security declarations. Operations marked unavailable have no configured
    public gateway route.


    ## Read the operation contract


    Response envelopes, pagination and retry rules differ by endpoint. HTTP
    success alone does not prove external fiscal completion or movement of
    money. Reconcile ambiguous writes before retrying. Use [responses and
    recovery](https://docs.gigstack.io/responses) and the operation's error
    codes; document credits and daily limits are not generic retryable rate
    limits.


    The issuing team's configuration selects Mexico or Colombia; customer
    country and currency do not. Read
    [Mexico](https://docs.gigstack.io/countries/mexico) or
    [Colombia](https://docs.gigstack.io/countries/colombia) before choosing
    fiscal fields. Accepted public input differs from a provider's direct
    payload.


    Examples and schema checks do not imply every operation has been executed
    live. [Verification coverage](https://docs.gigstack.io/verification)
    distinguishes source review, offline checks and observed staging behavior.
    Documentation describes operations and does not authorize execution.
  version: 2.0.0
  contact:
    name: Gigstack API Support
    url: https://gigstack.io
    email: support@gigstack.io
  license:
    name: Proprietary
    url: https://gigstack.io/terms
  termsOfService: https://gigstack.io/terms
servers:
  - url: https://api.gigstack.io/v2
    description: >
      Public API for standard live and test-mode keys. Test data is isolated by
      the key mode

      (`livemode: false`). Internal staging is a separate deployment and key
      store; see

      https://docs.gigstack.io/authentication#environments for its base URL.
security:
  - bearerAuth: []
tags:
  - name: gigstack Connect
    description: >
      **Multi-Team Resource Access**


      gigstack Connect lets a master team act on other teams that share its
      billing account.


      ## 🔗 How It Works


      Add the `team` query parameter to a request made with an **API key**:


      ```bash

      # Access team_xyz789's clients

      GET /clients?team=team_xyz789


      # Create an income invoice for team_abc123

      POST /invoices/income?team=team_abc123


      # Update service in team_def456

      PUT /services/service_456?team=team_def456

      ```


      ## ✅ Requirements


      - The API key's team must be a master team (gigstack Connect enabled)

      - The target team must exist and share the master team's billing account

      - The plan must include the `multipleIssuerAccounts` feature

      - OAuth access tokens cannot act on another team


      ## ⚠️ Error Responses


      Raw `{ "message": … }` bodies from the authentication layer:


      - `401 Unauthorized, not a master team` - gigstack Connect not enabled on
      your key's team

      - `404 Team not found` - Target team doesn't exist

      - `401 Unauthorized, no matched teams` - Target team could not be resolved
      within your billing account

      - `403 Tu plan no incluye múltiples cuentas emisoras. …` - Plan lacks
      `multipleIssuerAccounts`

      - `403 Team mismatch with OAuth token` - OAuth access token used with
      another team's id


      ## 🌐 Availability


      The `team` parameter is read by the authentication layer, so it is
      accepted on every authenticated

      endpoint, including ones whose parameter list does not show it.
  - name: Clients
    description: Client management operations with Mexican tax compliance
  - name: Services
    description: Service and product catalog management with SAT product keys
  - name: Invoices
    description: Invoice management with CFDI 4.0 compliance and SAT integration
  - name: Draft Invoices (Pre-Facturas)
    description: >
      **Create, edit, preview and stamp draft invoices (pre-facturas)**


      Draft invoices let you build CFDI invoices incrementally before stamping
      them with SAT. Use them as **pre-facturas** — generate a preview PDF with
      a "Sin Validez Fiscal" watermark to share with your client for approval,
      then stamp the draft to create a valid CFDI when ready.


      ## Typical Workflow


      1. `POST /invoices/draft` — Create a draft with minimal data

      2. `PUT /invoices/draft/{id}` — Update as more data becomes available

      3. `POST /invoices/draft/{id}/preview` — Generate a preview PDF
      (pre-factura)

      4. `POST /invoices/draft/{id}/stamp` — Finalize into a valid CFDI invoice
  - name: Descarga Masiva SAT
    description: >
      **SAT bulk invoice download via FIEL authentication**


      Download all your issued and received CFDI invoices directly from the SAT
      (Servicio de Administración Tributaria) using your FIEL (Firma Electrónica
      Avanzada).


      ## Setup flow

      1. `GET /invoices/download/activate/status` — Check if activated and
      what's needed

      2. `POST /invoices/download/activate` — Activate billing (adds Stripe
      meter/add-on)

      3. `POST /invoices/download/fiel` — Upload `.cer` + `.key` files
      (auto-registers with SAT)

      4. `PUT /invoices/download/schedule` — Configure daily auto-sync

      5. `POST /invoices/download/request` — Submit manual download requests


      ## Pricing

      - Included in Pro/Business plans: only the download meter ($0.20 MXN/XML)

      - Other paid plans: the same $0.20 MXN/XML download meter, no monthly base
      fee
  - name: Payments
    description: Payment processing, tracking, and refund management
  - name: Receipts
    description: Receipt creation and management with CFDI stamping capabilities
  - name: Retentions
    description: >-
      Tax retention documents (CFDI Retenciones 2.0) — creation, stamping,
      cancellation, and file retrieval
  - name: Platform Payouts
    description: >
      **Plan and stamp a marketplace's provider payouts from two files.**


      For marketplaces and digital platforms that pay providers under the SAT
      digital-platforms scheme

      (Plataformas Tecnológicas, RESICO 625, retention key 26): ride-hailing
      drivers, delivery couriers,

      lodging hosts, sellers of goods. Available to marketplace **master teams**
      whose billing account has

      platform payouts enabled. Upload a movements file and a commissions file.
      gigstack matches each row

      to a provider's team in your billing account and plans three kinds of
      CFDI: the provider's income

      invoice to you, your retention certificate (key 26) to the provider, and
      your monthly commission

      invoice to the provider.


      **Not for your own sales.** This is for a platform invoicing on behalf of
      its providers. A company

      invoicing its own sales, one CFDI per sale, should use `POST
      /invoices/income`.


      **Tax policy per account.** Which documents are issued, and with which SAT
      keys and rates, is set

      per master account at onboarding: allowed tax regimes, CSD requirement,
      service type (`tipoDeServ` /

      `subTipServ`), ISR and IVA withholding rates, product keys and concept
      descriptions. The defaults are

      for ground passenger transport (service type `01`, 2.1% ISR withholding).
      Contact support to

      configure your account's policy; it can't be changed through the API.


      1. `POST /platform-payouts` with an `Idempotency-Key` - upload and plan
      (synchronous)

      2. `GET /platform-payouts/{id}` and `GET /platform-payouts/{id}/movements`
      - review the plan

      3. `POST /platform-payouts/{id}/confirm` - irreversible hand-off to the
      stamping worker

      4. `GET /platform-payouts/{id}` - poll until `completed` or `failed`, then
      read `result`
         (`completed`, `partially_completed` or `failed`)

      Error messages and exclusion reasons are Spanish sentences for end users;
      branch on `error.code`,

      `reason_code` and `exclusion_codes`.
  - name: Documents
    description: >
      SAT supporting documentation (contracts, delivery/payment proofs,
      communications) — upload

      metadata, compliance review, AI extraction, and linking to invoices,
      payments, receipts and clients.
  - name: Teams
    description: Team management, settings, and member administration
  - name: Users
    description: User account management and password operations
  - name: Auth
    description: >
      **API-only signup for AI agents and partner integrations.**


      A single `POST /v2/auth/signup` call provisions a Firebase Auth user,
      billing

      account, team, plan subscription, and returns API keys — no UI, no FIEL
      upload,

      no human onboarding required.


      Designed for the AI-agents-as-customers use case. RFC defaults to genérico

      (`XAXX010101000`) so agents can transact under público en general
      until/unless

      their customer uploads their own RFC.


      Authenticated with `X-Internal-API-Key` (partner-issued) — Bearer tokens
      are

      team-scoped and a brand-new caller doesn't have one yet.


      See `AGENTS.md` in the gigstack-cli repo for end-to-end integration guide.
  - name: Webhooks
    description: Webhook management for real-time event notifications
  - name: Catalogs
    description: >
      **Read-only search over the SAT catalogs**


      Look up the SAT codes required on CFDI line items without hardcoding them:


      - `GET /catalogs/product-keys` — `c_ClaveProdServ`, the item `product_key`

      - `GET /catalogs/unit-keys` — `c_ClaveUnidad`, the item `unit_key` /
      `unit_name`


      Both are typo-tolerant full-text searches ranked by relevance. The
      catalogs are

      published by the SAT and identical for every team, so results carry no
      team data

      and ignore `livemode` — but a valid API key is still required.
  - name: SAT Lists
    description: >
      Read-only access to the RFC lists the SAT publishes under Artículo 69,
      69-B and 69-B Bis.


      gigstack re-syncs all 22 lists from the SAT's published CSVs every Sunday,
      so you can screen a counterparty's

      RFC before invoicing it without scraping the SAT yourself.
externalDocs:
  description: Complete API Documentation & Guides
  url: https://docs.gigstack.io
paths:
  /teams:
    post:
      tags:
        - Teams
      summary: Create team
      description: >
        Create a new team.


        Requires the `multipleIssuerAccounts` feature on your plan → `403
        insufficient_permissions` without it.


        **gigstack Connect:** Create teams using the `team` parameter.


        Requires a plan with the "Proveedores" feature: otherwise the call
        answers `401` with

        `You should subscribe to a plan that allows "Proveedores" feature.`
        (standardized envelope).
      operationId: createTeams
      parameters:
        - $ref: '#/components/parameters/TeamParameter'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamInput'
            example:
              address:
                country: MEX
                street: Av. Reforma
                zip: '11000'
                city: Ciudad de México
                state: CDMX
                exterior: '456'
                municipality: Miguel Hidalgo
                neighborhood: Polanco
              brand:
                alias: Empresa Innovadora
                primary_color: '#2563eb'
                secondary_color: '#1d4ed8'
                logo: https://example.com/logo.png
              support_email: soporte@empresa.com
              support_phone: +52 55 9876 5432
              tax_id: EIN850123ABC
              tax_system: '601'
              generate_onboarding_url: true
              add_members:
                - id: user123abc
                  role: editor
                - id: user456def
                  role: viewer
              add_master_team_members: false
              legal_name: Empresa de Tecnología S.A. de C.V.
              credit_limit: 1000
      responses:
        '201':
          description: >-
            Team created. `onboarding_url` is included when requested with
            `generate_onboarding_url`.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                  - timestamp
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    allOf:
                      - $ref: '#/components/schemas/ApiPublicTeam'
                      - type: object
                        properties:
                          onboarding_url:
                            type: string
                            nullable: true
                  message:
                    type: string
                  timestamp:
                    type: integer
                    format: int64
              example:
                success: true
                data:
                  id: team_1234567890
                  legal_name: MI EMPRESA EJEMPLO SA DE CV
                  address:
                    street: Av. Paseo de la Reforma
                    exterior: '222'
                    neighborhood: Juárez
                    city: Ciudad de México
                    state: CDMX
                    zip: '06600'
                    country: MEX
                  brand:
                    alias: Mi Empresa
                    primary_color: '#1F2937'
                    secondary_color: '#10B981'
                    logo: null
                  settings:
                    default_description: null
                    emails:
                      invoices_bcc: []
                      avoid_invoice_emails: false
                      avoid_test_invoice_emails: true
                      avoid_receipts_emails: false
                    global_invoice_disabled: false
                    use: G03
                    periodicity:
                      label: Mes
                      value: month
                  members:
                    - id: user_1234567890
                      email: admin@ejemplo.com
                      role: admin
                  owner: user_1234567890
                  support_email: soporte@ejemplo.com
                  support_phone: '+525512345678'
                  tax_id: MEE200101ABC
                  tax_system: '601'
                  created_at: 1767225600000
                  sat:
                    completed: true
                    connected_at: 1767225600000
                    csd_expires_at: 1893456000000
                  integrations:
                    stripe:
                      completed: false
                      category: null
                  metadata: {}
                  credit_limit: null
                  used_credits: 12
                  credit_period_start: 1767225600000
                  status: active
                  scheduled_deletion: null
                  onboarding_url: >-
                    https://embeded.gigstack.pro/?sessionId=otpOnboarding_7Kd2Pq&c=193847
                message: Team created successfully
                timestamp: 1767225600000
        '400':
          description: >-
            Body validation failed (`validation_failed`), or `Only livemode
            teams are allowed to be created` (`invalid_request_body`) when
            called with a test key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
              examples:
                test_key:
                  summary: Test-mode key
                  value:
                    success: false
                    error:
                      code: invalid_request_body
                      message: Only livemode teams are allowed to be created
                    timestamp: 1767225600000
                validation:
                  summary: Invalid body
                  value:
                    success: false
                    error:
                      code: validation_failed
                      message: Request validation failed
                      details:
                        - 'tax_id: Expected string'
                    timestamp: 1767225600000
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AuthForbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
components:
  parameters:
    TeamParameter:
      name: team
      in: query
      required: false
      schema:
        type: string
      description: >
        **gigstack Connect:** Target team ID for multi-team access.


        Requires gigstack Connect enabled on your team and shared billing
        account.


        Also requires the `multipleIssuerAccounts` feature on your plan.
        Requests targeting a

        team other than the one your API key belongs to return `403` without it.


        Only API keys can use it: an OAuth access token sent with another team's
        id is rejected with

        `403 Team mismatch with OAuth token`.


        **Optional — omit it entirely** unless you are acting on another team.
        It deliberately

        carries no example value so generated snippets do not emit
        `?team=undefined`; when the

        parameter is absent, the team is derived from your API key.


        **Example:** `?team=team_xyz789`
  schemas:
    TeamInput:
      description: >
        Unknown top-level keys are rejected (`400 validation_failed` /
        `unexpected_key`) — body

        validation runs in strict allowlist mode. `team`, `livemode` and `owner`
        are reserved

        and injected by the auth middleware.
      type: object
      additionalProperties: false
      properties:
        address:
          type: object
          additionalProperties: false
          required:
            - country
          properties:
            country:
              example: MEX
              type: string
            street:
              example: Av. Insurgentes Sur
              type: string
              nullable: true
            zip:
              example: '03100'
              type: string
              nullable: true
            city:
              example: Ciudad de México
              type: string
              nullable: true
            state:
              example: CDMX
              type: string
              nullable: true
            exterior:
              example: '123'
              type: string
              nullable: true
            interior:
              example: 4B
              type: string
              nullable: true
            municipality:
              example: Benito Juárez
              type: string
              nullable: true
            neighborhood:
              example: Del Valle
              type: string
              nullable: true
          nullable: true
        brand:
          type: object
          additionalProperties: false
          required:
            - alias
          properties:
            alias:
              example: My Company
              type: string
            primary_color:
              example: '#FF0000'
              type: string
              nullable: true
            secondary_color:
              example: '#00FF00'
              type: string
              nullable: true
            logo:
              type: string
              nullable: true
              example: https://example.com/logo.png
          nullable: true
        support_email:
          example: support@company.com
          type: string
          nullable: true
        support_phone:
          example: +52 55 1234 5678
          type: string
          nullable: true
        legal_name:
          description: Legal name of the team/company
          example: Empresa de Tecnología S.A. de C.V.
          type: string
          nullable: true
        tax_id:
          example: ABC123456789
          type: string
          nullable: true
        tax_system:
          example: '601'
          type: string
          nullable: true
        generate_onboarding_url:
          description: Generate onboarding URL for team setup
          example: true
          type: boolean
          nullable: true
        metadata:
          description: Additional metadata to store with the team
          type: object
          additionalProperties: true
          properties: {}
          nullable: true
        add_members:
          description: Array of members to add to the team on creation
          example:
            - id: user123abc
              role: editor
            - id: user456def
              role: admin
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - id
            properties:
              id:
                description: User ID to add as a team member
                example: user123abc
                type: string
              role:
                description: >-
                  Role for the team member. Defaults to "viewer" if not
                  specified.
                example: editor
                default: viewer
                type: string
                nullable: true
          nullable: true
        add_master_team_members:
          description: >-
            When true, copies all members from the master team to the newly
            created team with their existing permissions
          example: false
          type: boolean
          nullable: true
        credit_limit:
          description: >-
            Maximum number of documents (credits) the team can create per
            billing period. When null or omitted, the team shares the billing
            account pool with no per-team cap. On update it is applied only when
            the request is made with an API key of another team of the same
            billing account (the managing team); a team cannot change its own
            limit, and the field is ignored in that case.
          example: 1000
          type: number
          nullable: true
    ApiPublicTeam:
      type: object
      properties:
        id:
          type: string
          example: team_1234567890
        legal_name:
          type: string
          nullable: true
          example: Empresa de Tecnología S.A. de C.V.
          description: Official registered legal name of the company/team
        address:
          type: object
          nullable: true
          properties:
            country:
              type: string
              nullable: true
              example: MEX
            street:
              type: string
              nullable: true
              example: Av. Insurgentes Sur 456
            zip:
              example: '03100'
              type: string
              nullable: true
            city:
              example: Ciudad de México
              type: string
              nullable: true
            state:
              example: CDMX
              type: string
              nullable: true
            exterior:
              type: string
              nullable: true
              example: '96'
            interior:
              type: string
              nullable: true
              example: '10'
            neighborhood:
              type: string
              nullable: true
              example: Polanco
        brand:
          type: object
          properties:
            alias:
              type: string
              nullable: true
              example: Mi Empresa
            primary_color:
              type: string
              nullable: true
              example: '#007bff'
            secondary_color:
              type: string
              nullable: true
              example: '#6c757d'
            logo:
              type: string
              nullable: true
              example: https://example.com/logo.png
        settings:
          type: object
          nullable: true
          properties:
            avoid_automations_on_currencies:
              type: array
              nullable: true
              items:
                type: string
              example:
                - USD
                - EUR
            default_description:
              type: string
              nullable: true
              example: Default invoice description
            taxes:
              type: array
              nullable: true
              items:
                type: object
            taxes_usd:
              oneOf:
                - type: array
                  nullable: true
                  items:
                    type: object
                - type: boolean
                  nullable: true
            emails:
              type: object
              properties:
                invoices_bcc:
                  type: array
                  nullable: true
                  items:
                    type: string
                  example:
                    - accounting@example.com
                avoid_invoice_emails:
                  type: boolean
                  nullable: true
                  example: false
                avoid_test_invoice_emails:
                  example: true
                  type: boolean
                  nullable: true
                avoid_receipts_emails:
                  type: boolean
                  nullable: true
                  example: false
            override_item_description:
              type: string
              nullable: true
              example: Custom item description
            global_invoice_disabled:
              type: boolean
              nullable: true
              example: false
            complements:
              type: array
              nullable: true
              items:
                type: object
                properties:
                  data:
                    type: string
                    nullable: true
                  description:
                    type: string
                    nullable: true
                  type:
                    type: string
                    nullable: true
            uses_on_self_invoice_portal:
              type: array
              nullable: true
              items:
                type: string
              example:
                - G03
                - S01
            invoice_pdf_notes:
              type: string
              nullable: true
              example: Additional notes for PDF
            product_key:
              type: string
              nullable: true
              example: '81112209'
            unit_key:
              example: E48
              type: string
              nullable: true
            use:
              example: G03
              type: string
              nullable: true
            automate_complement_for_ppd_invoices:
              example: true
              type: boolean
              nullable: true
            withholding_taxes:
              type: array
              nullable: true
              items:
                type: object
            customer_portal_id:
              type: string
              nullable: true
              example: portal_1234567890
            periodicity:
              type: object
              nullable: true
              properties:
                label:
                  type: string
                  example: Mes
                value:
                  type: string
                  example: month
            default_series:
              type: object
              properties:
                income:
                  type: object
                  properties:
                    serie:
                      type: string
                      nullable: true
                      example: A
                complements:
                  type: object
                  properties:
                    serie:
                      type: string
                      nullable: true
                      example: P
                credit_note:
                  type: object
                  properties:
                    serie:
                      type: string
                      nullable: true
                      example: NC
        tax_id:
          type: string
          nullable: true
          example: EMP800101ABC
        tax_system:
          example: '601'
          type: string
          nullable: true
        support_email:
          type: string
          nullable: true
          example: support@empresa.com
        support_phone:
          example: +52 55 1234 5678
          type: string
          nullable: true
        owner:
          type: string
          nullable: true
          example: user_1234567890
        created_at:
          type: number
          nullable: true
          example: 1677651234
        sat:
          type: object
          properties:
            completed:
              example: true
              type: boolean
              nullable: true
            connected_at:
              type: number
              nullable: true
              example: 1677651234
            csd_expires_at:
              type: number
              nullable: true
              example: 1924991999
        members:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                nullable: true
                example: user_1234567890
              email:
                type: string
                nullable: true
                example: member@empresa.com
              role:
                type: string
                nullable: true
                example: admin
        integrations:
          type: object
          properties:
            stripe:
              type: object
              properties:
                completed:
                  type: boolean
                  nullable: true
                  example: false
                category:
                  type: string
                  nullable: true
                  example: payments
            mercadopago:
              type: object
              properties:
                completed:
                  type: boolean
                  nullable: true
                  example: false
                category:
                  type: string
                  nullable: true
                  example: payments
            clip:
              type: object
              properties:
                completed:
                  type: boolean
                  nullable: true
                  example: false
                category:
                  type: string
                  nullable: true
                  example: payments
            whmcs:
              type: object
              properties:
                completed:
                  type: boolean
                  nullable: true
                  example: false
                category:
                  type: string
                  nullable: true
                  example: payments
            paypal:
              type: object
              properties:
                completed:
                  type: boolean
                  nullable: true
                  example: false
                category:
                  type: string
                  nullable: true
                  example: payments
            openpay:
              type: object
              properties:
                completed:
                  type: boolean
                  nullable: true
                  example: false
                category:
                  type: string
                  nullable: true
                  example: payments
            conekta:
              type: object
              properties:
                completed:
                  type: boolean
                  nullable: true
                  example: false
                category:
                  type: string
                  nullable: true
                  example: payments
            bank:
              type: object
              properties:
                completed:
                  type: boolean
                  nullable: true
                  example: false
                category:
                  type: string
                  nullable: true
                  example: payments
            shopify:
              type: object
              properties:
                completed:
                  type: boolean
                  nullable: true
                  example: false
                category:
                  type: string
                  nullable: true
                  example: payments
            zapier:
              type: object
              properties:
                completed:
                  type: boolean
                  nullable: true
                  example: false
                category:
                  type: string
                  nullable: true
                  example: payments
            airtable:
              type: object
              properties:
                completed:
                  type: boolean
                  nullable: true
                  example: false
                category:
                  type: string
                  nullable: true
                  example: payments
            google_sheets:
              type: object
              properties:
                completed:
                  type: boolean
                  nullable: true
                  example: false
                category:
                  type: string
                  nullable: true
                  example: payments
            hilos:
              type: object
              properties:
                completed:
                  type: boolean
                  nullable: true
                  example: false
                category:
                  type: string
                  nullable: true
                  example: messaging
        credit_limit:
          type: number
          nullable: true
          example: 1000
          description: >-
            Maximum number of documents (credits) the team can create per
            billing period. Null means no per-team limit (shared billing account
            pool).
        used_credits:
          type: number
          example: 250
          description: Number of credits used by this team in the current billing period.
        credit_period_start:
          type: number
          nullable: true
          example: 1677651234000
          description: >-
            Unix timestamp (milliseconds) when the current credit period
            started. Resets each billing cycle.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          example:
            custom_field: value
        status:
          type: string
          nullable: true
          description: >-
            `pending_deletion` after `DELETE /teams/{id}`; otherwise usually
            absent or `active`.
          example: active
        scheduled_deletion:
          type: object
          nullable: true
          description: Set when the team is scheduled for deletion.
          properties:
            date:
              description: When the team will be deleted.
            flagged_at:
              type: integer
              format: int64
            flagged_by:
              type: string
    StandardErrorResponse:
      type: object
      description: >
        Standardized error envelope emitted by `sendErrorResponse` and its
        helpers

        (`sendValidationError`, `sendNotFoundError`, `sendUnauthorizedError`,

        `sendForbiddenError`, `sendConflictError`, `sendBadRequestError`,

        `sendInternalServerError`).
      required:
        - success
        - error
        - timestamp
      properties:
        success:
          type: boolean
          enum:
            - false
          example: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: >
                Stable machine-readable code. Values emitted by the shared
                helpers:

                `unauthorized`, `forbidden`, `invalid_token`,
                `validation_failed`,

                `invalid_request_body`, `missing_required_field`,
                `invalid_field_value`,

                `resource_not_found`, `resource_already_exists`,
                `resource_conflict`,

                `business_rule_violation`, `operation_not_allowed`,

                `insufficient_permissions`, `external_service_error`,

                `payment_processor_error`, `cfdi_service_error`,

                `internal_server_error`, `service_unavailable`,
                `rate_limit_exceeded`,

                `database_error`, `data_integrity_error`, `file_not_found`,

                `file_upload_error`, `invalid_file_format`. Individual handlers
                may

                emit additional endpoint-specific codes, documented per
                operation.
              example: validation_failed
            message:
              type: string
              example: Request validation failed
            details:
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
              description: >
                Present only when the handler supplies detail. Validation
                failures

                emit an array of `"<field path>: <message>"` strings.
              example:
                - 'currency: Field is required'
        timestamp:
          type: integer
          format: int64
          description: Server time in epoch milliseconds.
          example: 1767225600000
    AuthMiddlewareError:
      type: object
      description: >
        Raw error body produced by the authentication layer (before any endpoint
        runs). It is not

        the standardized envelope: there is no `success` and no `timestamp`.
      required:
        - message
      properties:
        message:
          type: string
          description: >-
            Human-readable reason. Some messages are in Spanish; branch on the
            HTTP status, not on this text.
          example: Unauthorized
        error:
          type: string
          description: >-
            OAuth error code. Present only when an OAuth access token was
            presented.
          enum:
            - invalid_token
            - token_expired
            - token_revoked
            - server_error
          example: token_expired
        error_description:
          type: string
          description: Same text as `message`. Present only alongside `error`.
          example: Access token has expired. Please refresh your token.
        details:
          description: >-
            Extra detail, e.g. `Invalid API Key` when a revoked key is rejected
            with `403`.
          oneOf:
            - type: string
            - type: object
          example: Invalid API Key
    UnauthorizedError:
      allOf:
        - $ref: '#/components/schemas/StandardErrorResponse'
      example:
        success: false
        error:
          code: unauthorized
          message: Unauthorized access
        timestamp: 1767225600000
  responses:
    Unauthorized:
      description: >
        Authentication failed. Two different bodies can come back with a `401`:


        1. **From the authentication layer**, before the endpoint runs: a raw
        object with
           `message` and — for OAuth access tokens only — `error` / `error_description`. It does
           **not** use the standardized envelope (`success` and `timestamp` are absent). Messages:
           `Unauthorized` (missing header, missing `Bearer ` prefix, unparseable token),
           `Unauthorized, missing team in token`, `Unauthorized, not a master team` and
           `Unauthorized, no matched teams` (gigstack Connect), `Invalid access token`,
           `Access token has expired. Please refresh your token.`, `Access token has been revoked`.
        2. **From the endpoint itself**: the standardized envelope with
        `error.code: unauthorized`.


        Branch on the HTTP status, not on the body shape.
      content:
        application/json:
          schema:
            anyOf:
              - $ref: '#/components/schemas/AuthMiddlewareError'
              - $ref: '#/components/schemas/UnauthorizedError'
          examples:
            missing_or_invalid_key:
              summary: Authentication layer — missing or unparseable API key
              value:
                message: Unauthorized
            oauth_token_expired:
              summary: Authentication layer — expired OAuth access token
              value:
                message: Access token has expired. Please refresh your token.
                error: token_expired
                error_description: Access token has expired. Please refresh your token.
            connect_not_master_team:
              summary: >-
                Authentication layer — `team` sent by a team without gigstack
                Connect
              value:
                message: Unauthorized, not a master team
            endpoint_envelope:
              summary: Endpoint — standardized envelope
              value:
                success: false
                error:
                  code: unauthorized
                  message: Unauthorized access
                timestamp: 1767225600000
    AuthForbidden:
      description: >
        Rejected by the authentication layer after the credential was
        recognised. The body is a raw

        object (`message`, sometimes `details`), **not** the standardized
        envelope. Causes:


        - The API key was revoked or disabled: `message: "API Key inválida."`,
        `details: "Invalid API Key"`.

        - The billing account's plan does not include API access. `message` is a
        Spanish sentence
          containing an HTML link to `https://app.gigstack.pro/memberships`. Branch on the status
          code; do not display or match the text.
        - gigstack Connect: the plan lacks the `multipleIssuerAccounts` feature
        (Spanish message
          starting `Tu plan no incluye múltiples cuentas emisoras.`), or an OAuth access token was
          sent with a `team` other than its own (`Team mismatch with OAuth token`).

        An endpoint may also answer `403` for its own reasons; those are
        documented on the

        operation when they exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthMiddlewareError'
          examples:
            revoked_api_key:
              summary: API key revoked or disabled
              value:
                message: API Key inválida.
                details: Invalid API Key
            plan_without_api_access:
              summary: Plan does not include API access
              value:
                message: >-
                  La API se encuentra disponible para un plan más grande, por
                  favor actualiza tu plan <a
                  href='https://app.gigstack.pro/memberships'>aquí</a> o ponte
                  en contacto con soporte.
            connect_plan_without_multiple_issuers:
              summary: gigstack Connect — plan lacks multipleIssuerAccounts
              value:
                message: >-
                  Tu plan no incluye múltiples cuentas emisoras. Actualiza tu
                  plan en https://app.gigstack.pro/memberships o ponte en
                  contacto con soporte para operar sobre otros equipos.
            oauth_team_mismatch:
              summary: gigstack Connect — OAuth token used for another team
              value:
                message: Team mismatch with OAuth token
    ServerError:
      description: >-
        Unexpected server error (`error.code: internal_server_error`). The
        failure is logged on gigstack's side.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StandardErrorResponse'
          example:
            success: false
            error:
              code: internal_server_error
              message: An internal server error occurred
            timestamp: 1767225600000
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        **Authentication Method:** HTTP Bearer token.


        The runtime requires the literal `Bearer ` prefix — a bare token in the

        `Authorization` header is rejected with `401 unauthorized`.


        **Header Format:** `Authorization: Bearer YOUR_API_KEY`


        Your API key is a JWT. Live keys operate on live data (`livemode:
        true`);

        test keys operate on isolated test data (`livemode: false`).


        **Get your key at:**
        [app.gigstack.pro/settings?tab=api](https://app.gigstack.pro/settings?tab=api)


        **Errors:** credential failures are answered by the authentication layer
        with a raw

        `{ "message": … }` body, not the standardized envelope — `401` for a
        missing, malformed or

        expired token, `403` for a revoked key or a plan without API access. See
        the `Unauthorized`

        and `AuthForbidden` responses.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.