openapi: 3.2.0 info: title: Bird Email Audiences API version: 1.0.0 description: 'The Bird API: one REST API for email, SMS, WhatsApp, verification, and Realtime.' servers: - url: https://{region}.platform.bird.com description: 'Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand. ' variables: region: default: us1 enum: - us1 - eu1 description: The region your organization's data is hosted in. - url: https://platform.bird.com description: Region-independent endpoint for authentication and account administration. - url: http://localhost:8080 description: Local development. security: - BearerAuth: [] tags: - name: email-audiences description: Audiences are the recipient lists broadcasts are sent to. An audience holds a set of contacts that you manage through the API. The contacts in the audience at send time become the broadcast's recipients after suppressions are applied. A contact can belong to multiple audiences. paths: /v1/audiences: post: operationId: createAudience x-snippet-key: audiences.create summary: Create an audience description: 'Creates an audience in the workspace. New audiences start empty: add members with Add contacts to an audience or through Create or update contacts in bulk. The `type` field currently accepts only `static` audiences.' tags: - email-audiences security: - BearerAuth: [] - CookieAuth: [] x-audiences: - public - command parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AudienceCreateRequest' responses: '201': description: The created audience. headers: Idempotency-Replay: $ref: '#/components/headers/IdempotencyReplay' content: application/json: schema: $ref: '#/components/schemas/Audience' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' x-surfaces: - attio - cli - make - mcp - n8n - sdk get: operationId: listAudiences x-snippet-key: audiences.list summary: List audiences description: Returns a paginated list of audiences in the workspace, newest first. Filter to audiences whose name contains a substring with `q`. tags: - email-audiences security: - BearerAuth: [] - CookieAuth: [] x-audiences: - public - command parameters: - name: q in: query required: false description: Case-insensitive substring match against the audience's name. schema: type: string minLength: 1 example: newsletter - $ref: '#/components/parameters/PaginationLimit' - $ref: '#/components/parameters/StartingAfter' - $ref: '#/components/parameters/EndingBefore' responses: '200': description: A page of audiences. content: application/json: schema: $ref: '#/components/schemas/AudienceList' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' x-surfaces: - attio - cli - make - mcp - n8n - sdk /v1/audiences/{audience_id}: get: operationId: getAudience x-snippet-key: audiences.get summary: Get an audience description: 'Returns a single audience: its name, description, and type. The member list is separate; fetch it with List an audience''s contacts.' tags: - email-audiences security: - BearerAuth: [] - CookieAuth: [] x-audiences: - public - command parameters: - name: audience_id in: path required: true description: ID of the audience to fetch. schema: $ref: '#/components/schemas/AudienceID' responses: '200': description: The audience. content: application/json: schema: $ref: '#/components/schemas/Audience' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' x-surfaces: - attio - cli - make - mcp - n8n - sdk patch: operationId: updateAudience x-snippet-key: audiences.update summary: Update an audience description: Updates an audience's name or description. Omitted fields are left unchanged; set `description` to `null` to clear it. tags: - email-audiences security: - BearerAuth: [] - CookieAuth: [] x-audiences: - public - command parameters: - name: audience_id in: path required: true description: ID of the audience to update. schema: $ref: '#/components/schemas/AudienceID' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AudienceUpdateRequest' responses: '200': description: The updated audience. content: application/json: schema: $ref: '#/components/schemas/Audience' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' x-surfaces: - cli - make - mcp - n8n - sdk delete: operationId: deleteAudience x-snippet-key: audiences.delete summary: Delete an audience description: Deletes an audience and its memberships. Contacts themselves are not deleted. An audience cannot be deleted while a broadcast targeting it is scheduled, accepted, sending, or canceling; cancel that broadcast first, then retry. tags: - email-audiences security: - BearerAuth: [] - CookieAuth: [] x-audiences: - public - command parameters: - name: audience_id in: path required: true description: ID of the audience to delete. schema: $ref: '#/components/schemas/AudienceID' - $ref: '#/components/parameters/IdempotencyKey' responses: '204': description: The audience was deleted. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' x-surfaces: - cli - make - mcp - n8n - sdk /v1/audiences/{audience_id}/contacts: get: operationId: listAudienceContacts x-snippet-key: audiences.list_contacts summary: List an audience's contacts description: Lists the contacts in a static audience as a cursor page, ordered by the time each contact joined the audience, most recent first. Each entry is the contact together with the time it joined. tags: - email-audiences security: - BearerAuth: [] - CookieAuth: [] x-audiences: - public - command parameters: - name: audience_id in: path required: true description: ID of the audience whose contacts to list. schema: $ref: '#/components/schemas/AudienceID' - name: q in: query required: false description: Case-insensitive substring match against a contact's email address or the digits in its international phone number. schema: type: string minLength: 1 example: acme.com - $ref: '#/components/parameters/PaginationLimit' - $ref: '#/components/parameters/StartingAfter' - $ref: '#/components/parameters/EndingBefore' responses: '200': description: A page of the audience's contacts. content: application/json: schema: $ref: '#/components/schemas/AudienceMemberList' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' x-surfaces: - cli - make - mcp - n8n - sdk post: operationId: assignAudienceContacts x-snippet-key: audiences.add_contacts summary: Assign contacts to an audience description: 'Adds up to 1,000 contacts to an audience. Adding is idempotent: contacts that are already members are left in place and keep their original join time. If any contact ID does not exist in the workspace, the whole request fails with `422 Unprocessable Entity` and no contacts are added.' tags: - email-audiences security: - BearerAuth: [] - CookieAuth: [] x-audiences: - public - command parameters: - name: audience_id in: path required: true description: ID of the audience to add contacts to. schema: $ref: '#/components/schemas/AudienceID' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AudienceContactsAddRequest' responses: '204': description: Contacts added to the audience. headers: Idempotency-Replay: $ref: '#/components/headers/IdempotencyReplay' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' x-surfaces: - attio - cli - make - mcp - n8n - sdk /v1/audiences/{audience_id}/contacts/remove: post: operationId: unassignAudienceContacts x-snippet-key: audiences.remove_contacts summary: Unassign contacts from an audience description: Removes up to 1,000 contacts from an audience. Contacts that are not members are skipped. If any contact ID does not exist in the workspace, the whole request fails with `422 Unprocessable Entity` and no memberships are removed. The contacts themselves are not deleted and remain members of any other audiences. tags: - email-audiences security: - BearerAuth: [] - CookieAuth: [] x-audiences: - public - command parameters: - name: audience_id in: path required: true description: ID of the audience to remove contacts from. schema: $ref: '#/components/schemas/AudienceID' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AudienceContactsRemoveRequest' responses: '204': description: Contacts removed from the audience. headers: Idempotency-Replay: $ref: '#/components/headers/IdempotencyReplay' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' x-surfaces: - attio - cli - make - mcp - n8n - sdk /v1/audiences/{audience_id}/contacts/{contact_id}: delete: operationId: unassignAudienceContact x-snippet-key: audiences.remove_contact summary: Unassign a contact from an audience description: Removes a contact's membership in an audience. The contact itself is not deleted and remains a member of any other audiences. Removing a contact that is not a member of the audience succeeds with no effect (`204 No Content`); an unknown audience or contact returns a not-found error. tags: - email-audiences security: - BearerAuth: [] - CookieAuth: [] x-audiences: - public - command parameters: - name: audience_id in: path required: true description: ID of the audience to remove the contact from. schema: $ref: '#/components/schemas/AudienceID' - name: contact_id in: path required: true description: ID of the contact to remove. schema: $ref: '#/components/schemas/ContactID' - $ref: '#/components/parameters/IdempotencyKey' responses: '204': description: The contact was removed from the audience, or was already not a member. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' x-surfaces: - cli - make - mcp - n8n - sdk components: schemas: AudienceContactsRemoveRequest: type: object additionalProperties: false required: - contact_ids properties: contact_ids: type: array minItems: 1 maxItems: 1000 items: $ref: '#/components/schemas/ContactID' description: Contacts to remove from the audience. Removing a contact that is not a member has no effect. Duplicate IDs in the list are collapsed. If any ID does not exist in the workspace, the whole request fails with a validation error and no memberships are removed. example: contact_ids: - con_01krdgeqcxet5s7t44vh8rt9mg AudienceID: type: string minLength: 1 pattern: ^adn_[0-9a-hjkmnp-tv-z]{26}$ example: adn_01krdgeqcxet5s7t44vh8rt9mg ErrorBody: type: object additionalProperties: false required: - type - code - name - message - doc_url - request_id properties: type: type: string minLength: 1 description: Broad category for coarse client branching. enum: - auth_error - bad_request_error - billing_error - conflict_error - gone_error - internal_error - misdirected_error - not_found_error - not_implemented_error - payload_too_large_error - permission_error - precondition_error - rate_limit_error - service_unavailable_error - too_early_error - validation_error code: type: string minLength: 1 pattern: ^E\d{5}$ description: Opaque, stable, unique error identifier. Never reused. name: type: string minLength: 1 description: Human-readable slug for log readability. Paired with code, never replaces it. message: type: string minLength: 1 description: Human-readable description. Not stable; clients must not parse it. param: type: string minLength: 1 description: Identifies the offending field. Omitted when not applicable. doc_url: type: string minLength: 1 format: uri description: Stable link to the docs page for this error code. request_id: type: string minLength: 1 description: Request correlation ID for support and troubleshooting. Also returned in the `X-Request-Id` response header. vendor_code: type: string minLength: 1 description: 'Verbatim error code from an external system, such as an SMTP response code or a payment decline code. Present only when the code may help you resolve the error. ' details: type: array description: Per-field validation errors. Present only on validation_error responses. items: $ref: '#/components/schemas/ErrorDetail' remediation: type: string minLength: 1 description: A human-readable next step to resolve this error. Present when a recovery is known. next: type: array description: 'The steps that resolve this error. Perform them in order, re-reading after each; a `wait` or `terminal` step is always last. Present for errors with a well-defined recovery, such as unmet preconditions and conflicts. ' items: $ref: '#/components/schemas/NextAction' AudienceList: allOf: - type: object required: - data properties: data: type: array description: Page of audience objects. items: $ref: '#/components/schemas/Audience' - $ref: '#/components/schemas/_ListEnvelope' Audience: allOf: - type: object required: - id - name - type - created_at - updated_at properties: id: readOnly: true $ref: '#/components/schemas/AudienceID' description: ID of the audience, accepted by every operation that takes an `audience_id`. name: type: string minLength: 1 maxLength: 100 description: Display name for the audience. description: type: - string - 'null' maxLength: 500 description: Longer description of who this audience is. type: type: string minLength: 1 enum: - static x-enum-varnames: - AudienceTypeStatic default: static description: How the audience's recipients are determined. `static` is an explicit member list you manage by adding and removing contacts. - $ref: '#/components/schemas/Timestamps' AudienceMemberList: allOf: - type: object required: - data properties: data: type: array description: Page of audience members, each a contact paired with the time it joined the audience. items: $ref: '#/components/schemas/AudienceMember' - $ref: '#/components/schemas/_ListEnvelope' AudienceContactsAddRequest: type: object additionalProperties: false required: - contact_ids properties: contact_ids: type: array minItems: 1 maxItems: 1000 items: $ref: '#/components/schemas/ContactID' description: Contacts to add to the audience. Adding a contact that is already a member has no effect and keeps its original join time. Duplicate IDs in the list are collapsed. If any ID does not exist in the workspace, the whole request fails with a validation error and no contacts are added. example: contact_ids: - con_01krdgeqcxet5s7t44vh8rt9mg AudienceUpdateRequest: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 100 description: New display name for the audience. Omit to keep the current name. The name cannot be cleared, and a whitespace-only value returns a validation error. description: type: - string - 'null' maxLength: 500 description: Longer description of who this audience is. Set to null to clear. example: name: Newsletter subscribers ContactID: type: string minLength: 1 pattern: ^con_[0-9a-hjkmnp-tv-z]{26}$ example: con_01krdgeqcxet5s7t44vh8rt9mg AudienceMember: type: object additionalProperties: false required: - contact - joined_at properties: contact: $ref: '#/components/schemas/Contact' joined_at: type: string format: date-time minLength: 1 readOnly: true description: When this contact joined the audience. Members are listed in join order, most recent first. audiences: type: array readOnly: true description: The audiences this contact belongs to, including the one being listed, most-recently-joined first. items: $ref: '#/components/schemas/AudienceRef' _ListEnvelope: type: object required: - next_cursor - prev_cursor - refresh_cursor properties: next_cursor: type: - string - 'null' description: Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists. example: eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9 prev_cursor: type: - string - 'null' description: Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists. example: null refresh_cursor: type: - string - 'null' description: Refresh anchor, the first row of this response. Pass back as `ending_before` to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-`null` whenever `data` is non-empty; `null` only on an empty page. Distinct from `prev_cursor`. example: eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9 Timestamps: type: object required: - created_at - updated_at properties: created_at: type: string format: date-time minLength: 1 readOnly: true example: '2026-05-20T09:14:52Z' updated_at: type: string format: date-time minLength: 1 readOnly: true example: '2026-05-25T16:42:01Z' ErrorDetail: type: object additionalProperties: false required: - param - message properties: param: type: string minLength: 1 description: 'Dotted field path, such as `to[0].email`, `subject`, or `.`. When the request was rejected for a query parameter the endpoint does not declare, this carries that parameter''s name instead of a field path. ' message: type: string minLength: 1 description: What is wrong with this field. AudienceRef: type: object additionalProperties: false required: - id - name description: A compact reference to an audience, carrying its ID and display name. properties: id: readOnly: true $ref: '#/components/schemas/AudienceID' description: ID of the referenced audience. name: type: string minLength: 1 maxLength: 100 description: The audience's display name. NextAction: type: object additionalProperties: false required: - kind - description properties: kind: type: string minLength: 1 x-extensible-enum: - operation - external - wait - terminal description: "What you do about this step.\n\n- `operation`: call the operation named in `operation`, then\n read again.\n- `external`: act somewhere this API does not reach, then read\n again.\n- `wait`: nothing is asked of you, so read again later.\n- `terminal`: nothing you do resolves this, so stop retrying.\n\nTolerate a value you do not recognize: show the `description` and\noffer no action.\n" description: type: string minLength: 1 description: A short, human-readable label for the step, suitable for display. operation: type: string minLength: 1 description: 'The operationId to call. Present only when `kind` is `operation`. The operation''s own schema says how to call it; this says only which one, and what to address it with. ' params: type: object additionalProperties: type: string minLength: 1 description: 'The parameters that address the operation, by name: `{"sender_id": "…"}` for an operation on `/v1/sms/senders/{sender_id}/requirements`. A parameter the operation takes in its query string is given the same way, so an operation addressed as `?subject_id=` carries `{"subject_id": "…"}`. Every parameter the call needs is here, whether its value came from the thing you were acting on or is fixed for this step, so you can make the call from this object alone. Present only when `kind` is `operation` and the operation names a subject. A request body, when the operation takes one, is described by the operation''s own schema and never appears here. ' url: type: string format: uri description: 'A URL to open. Present only when `kind` is `external`, and only when the step has one. An external step whose `description` says to go and do something with no URL to open is normal. ' AudienceCreateRequest: type: object additionalProperties: false required: - name properties: name: type: string minLength: 1 maxLength: 100 description: Display name for the audience. description: type: string maxLength: 500 description: Longer description of who this audience is. type: type: string enum: - static x-enum-varnames: - AudienceTypeStatic default: static description: How the audience's recipients are determined. `static` is an explicit member list you manage by adding and removing contacts. example: name: Newsletter subscribers description: Contacts who opted into the monthly product newsletter Error: type: object additionalProperties: false required: - error properties: error: $ref: '#/components/schemas/ErrorBody' Contact: allOf: - type: object required: - id - email - phone_number - created_at - updated_at properties: id: readOnly: true $ref: '#/components/schemas/ContactID' description: ID of the contact, accepted by every operation that takes a `contact_id`. email: type: - string - 'null' format: email maxLength: 254 description: The contact's email address, in its stored form, trimmed and lowercased before uniqueness is checked. Unique within the workspace. `null` when the contact has no email address. phone_number: type: - string - 'null' minLength: 5 maxLength: 16 description: 'The contact''s phone number in normalized international form: a leading `+` and four to 15 digits. We normalize formatting but do not verify the number against numbering-plan metadata. The number is unique within the workspace. Because carriers recycle disconnected numbers, use `external_id` as the durable key for your own records. `null` when the contact has no phone number.' first_name: type: - string - 'null' maxLength: 100 description: The contact's first name. Available in broadcast templates as `bird.contact.first_name`. last_name: type: - string - 'null' maxLength: 100 description: The contact's last name. Available in broadcast templates as `bird.contact.last_name`. external_id: type: - string - 'null' maxLength: 254 description: Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set. data: type: object additionalProperties: true description: 'Custom property values for this contact, available in broadcast templates as `bird.contact.`. Each key is a property created via the contact properties API, and each value is a string, number, boolean, or RFC 3339 datetime matching the property''s declared type (strings up to `500` characters). Total size is capped at 2 KB serialized. Values stored under a property that was later archived remain readable here. ' audiences: type: array readOnly: true description: The audiences this contact belongs to, most-recently-joined first. Only present when listing contacts; omitted from every other contact operation. items: $ref: '#/components/schemas/AudienceRef' - $ref: '#/components/schemas/Timestamps' parameters: PaginationLimit: name: limit in: query required: false description: Maximum number of items to return per page. schema: type: integer minimum: 1 maximum: 100 default: 25 IdempotencyKey: name: Idempotency-Key in: header required: false description: "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n" schema: type: string maxLength: 255 StartingAfter: name: starting_after in: query required: false description: Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order. schema: type: string EndingBefore: name: ending_before in: query required: false description: Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. schema: type: string responses: InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Rate limit exceeded headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: 'The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation. ' headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' Unprocessable: description: 'The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`. ' content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: Resource conflict content: application/json: schema: $ref: '#/components/schemas/Error' headers: RetryAfter: description: 'Number of seconds to wait before retrying the request. ' schema: type: integer minimum: 0 example: 35 IdempotencyReplay: description: The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again. schema: type: string enum: - 'true' RateLimit: description: 'Remaining capacity for the request''s rate-limit policy as an IETF Structured Field. Format: `"";r=;t=`. ' schema: type: string example: '"email_send";r=842;t=35' RateLimit-Policy: description: 'Effective quota for the request''s rate-limit policy as an IETF Structured Field. Format: `"";q=;w=`. ' schema: type: string example: '"email_send";q=1000;w=60' securitySchemes: BearerAuth: type: http scheme: bearer description: 'Pass the API key as a bearer token in the `Authorization` header. Keys use the format `bk_{region}_*`. The prefix identifies the region and selects the API endpoint. Official Bird SDKs and the CLI derive the region from the key. ' CookieAuth: type: apiKey in: cookie name: bird_session description: 'Session cookie set after signing in to the Bird dashboard. The cookie value is an opaque session token; no session data is stored in the cookie itself. ' RealtimeKey: type: apiKey in: header name: X-Realtime-Key description: 'The Realtime app key. Together with `X-Realtime-Secret`, it authenticates a request to the Realtime API in addition to the workspace credential. Both values come from the app''s credentials and must belong to the calling workspace. Official Bird SDKs accept the pair as client configuration. ' RealtimeSecret: type: apiKey in: header name: X-Realtime-Secret description: 'The Realtime app secret paired with `X-Realtime-Key`. The API returns the secret only when the key is created and does not store it. Create a new key and revoke the current key if you lose the secret. Official Bird SDKs accept the pair as client configuration. '