Ingestion API

The ingestion API can be used to upload data to Birdie directly. Clients upload data by making an HTTP PUT for each record they want to upload.

The request must include a Birdie API key in an HTTP header in the form:

Authorization: ApiKey {api-key}

To generate an API key, you can reach out to the Birdie team and we will provide you one.

Response status codes

• 201 Created on success

• 400 Bad Request if the request body is invalid (response body will be a JSON object with an error message)

• 401 Unauthorized if the API key is missing or invalid

• 503 Service Unavailable if too many requests are being made in a short amount of time

We suggest making up to 100 requests per second (6000 per minute) to the Birdie API to avoid 5XX errors.

JSON formats

Most ingestion endpoints accept JSON payloads.

Audio ingestion is the exception and uses multipart/form-data because it contains both structured metadata and binary recording content.

Schema definitions for JSON payloads are available at: https://api.birdie.ai/ingestion/schemas

Types of uploads

Conversations and Messages

A conversation is an identifier of a discussion between one or more users (e.g., a support ticket or a GitHub issue).

A message is part of a conversation; a conversation is composed of messages.

Conversations and messages must be uploaded together (we suggest uploading the conversation first, then its messages). Conversations don't appear inside Birdie if they don't have an associated conversation message and vice-versa. Birdie calculates a summary for each conversation based on its messages, which is shown in the feed and can be expanded to see individual messages.

Feedbacks

A single feedback record posted by a user (e.g., NPS response or app review). Feedbacks are displayed alongside conversation summaries in the feed.

Audios

An Audio represents a recording file and the metadata required to process it.

Both components must be submitted together in the same request.

Audience: Accounts and Users (optional)

Accounts and users are optional records to further segment feedbacks and conversations. Use account-id and author-id fields inside the kind fields of feedbacks or conversation messages. After uploading feedbacks/conversations, you can upload accounts and users.

Kinds

For conversations, messages, and feedbacks, the schema includes a kind field to distinguish different kinds (e.g., support_ticket, review). Kinds add fields specific to the origin of the data.

Kinds are used to add more fields that are more specific to the origin of the data.

For example, for conversations and messages, the Zendesk Tickets example falls under the support_ticket kind. The app store user review example falls under the review kind.

We have multiple kinds, which can be listed here: https://api.birdie.ai/ingestion/schemas

You will need to analyze your source of data and see which record type (so Conversation vs Feedbacks) and which Kind best fits your data.

The value of the kind field within a feedback, conversation or conversation message is always an object with two fields:

• name: specifies the kind

• fields: contains data specific to this kind.

The valid kinds and their schemas are documented at the URL given above.

Other common concepts

• Path parameters in endpoints are identifiers for records. They should be strings (alpha-numerical suggested) and must be unique for records that co-exist in your Birdie account.

• Common fields across record types:

  • additional_fields: lets clients upload any fields that don't fit the pre-defined schema (can be mapped to custom fields in Birdie — contact Birdie team for setup).

  • batch_id: optional field to group uploaded records into a batch. Guidelines:

    1. Upload all records with the same batch_id within 24 hours.

    2. Avoid using a different batch_id for each record (this would create too many batches).

Size limitations

The payload / row for any type of event (e.g an entire conversation upload with all its messages, an entire feedback, or an entire account upload) will be serialized into a JSON object by Birdie, which has a size limit of 10MB.

IMPORTANT: Payloads larger than 10MB will error out and not be ingested.

Endpoints

There are five endpoints to upload different types of data.

Conversations endpoint

PUT /ingestion/conversations/{conversation-id}

Use to create or update a conversation. Updates overwrite the entire record (no partial updates).

The messages belonging to the conversation are uploaded separately.

Example 1 - Conversation of kind support_ticket

curl

curl https://api.birdie.ai/ingestion/conversations/123 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "kind": {
      "name": "support_ticket",
      "fields": {
        "subject": "Account reset",
        "status": "open",
        "priority": "normal",
        "channel": "email"
      }
    },
    "additional_fields": {
      "ticket_opened_at": "2024-01-01T00:00:00Z"
    }
  }'

Example 2 - Conversation of kind issue

curl

curl https://api.birdie.ai/ingestion/conversations/issue-1 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "kind": {
      "name": "issue",
      "fields": {
        "project_id": "birdie/repository",
        "project_name": "repository",
        "status": "open",
        "title": "Doesnt work after update 1.01"
      }
    },
    "additional_fields": {
      "issue_opened_at": "2024-01-01T00:00:00Z",
      "repository_tags": ["repo"]
    }
  }'

Messages endpoint

PUT /ingestion/conversations/{conversation-id}/messages/{message-id}

Use to create or update a message that belongs to a conversation. Updates overwrite the entire record (no partial updates).

The conversation ID must match a conversation uploaded separately. Order of uploads (conversation vs messages) is not important.

Example 1 - Message of kind support_ticket

curl

curl https://api.birdie.ai/ingestion/conversations/123/messages/456 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "kind": {
      "name": "support_ticket",
      "fields": {
        "author_id": "author-1",
        "author_name": "John Doe",
        "author_type": "Agent"
      }
    },
    "text":"Hello, My name is John! Im here to assist you today.",
    "language":"en",
    "posted_at":"2024-01-01T00:00:00Z",
    "additional_fields": {
      "high_priority": true
    }
  }'

Example 2 - First message of kind issue by User

curl

curl https://api.birdie.ai/ingestion/conversations/issue-1/messages/issue-msg-1 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "kind": {
      "name": "issue",
      "fields": {
        "author_id": "engineer123",
        "author_name": "John"
      }
    },
    "text":"Since the last update, I cant get the service to work!",
    "language":"en",
    "posted_at":"2024-01-01T10:00:00Z",
    "additional_fields": {
      "thumbs_up": 5,
      "thumbs_down": 3
    }
  }'

Example 3 - Second message of kind issue by another user

curl

curl https://api.birdie.ai/ingestion/conversations/issue-1/messages/issue-msg-2 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "kind": {
      "name": "issue",
      "fields": {
        "author_id": "contributor456",
        "author_name": "Josh"
      }
    },
    "text":"Try rolling back to the last version, that worked for me",
    "language":"en",
    "posted_at":"2024-01-01T10:15:00Z",
    "additional_fields": {
      "thumbs_down": 10
    }
  }'

Feedbacks endpoint

PUT /ingestion/feedbacks/{feedback-id}

Use to create or update feedbacks that don't belong to a conversation. Updates overwrite the entire record (no partial updates).

Example 1 - Feedback of kind review

curl

curl https://api.birdie.ai/ingestion/feedbacks/abcd-123 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "posted_at": "2024-01-01T00:00:00Z",
    "text": "Excellent app",
    "language": "en",
    "kind": {
      "name": "review",
      "fields": {
        "owner": "Owner",
        "rating": 5.0
      }
    },
    "additional_fields": {
      "author": "John Doe",
      "device": "Android"
    }
  }'

Example 2 - Feedback of kind nps

curl

curl https://api.birdie.ai/ingestion/feedbacks/xyzw-451 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "posted_at": "2024-01-01T00:00:00Z",
    "text": "Im always recommending this service to my friends!",
    "language":"en",
    "kind": {
      "name": "nps",
      "fields": {
        "author_id": "john123",
        "author_name": "John Doe",
        "account_id": "companyABC",
        "title": "[NPS 2024] How Likely are you to recommend Birdie?",
        "rating": 10
      }
    },
    "additional_fields": {
      "classification": "promoter"
    }
  }'

Audios endpoint

PUT /ingestion/audios/{recording-id}

This endpoint is used to upload (create or update) an Audio.

The request must use multipart/form-data and contain:

• A metadata part containing a JSON payload.

• A file part containing the audio recording.

  • Supported recording formats depend on the transcription pipeline. In general, any common audio-only format is expected to work, including:

    • WAV

    • MP3

  • If you intend to use a different format, please reach out to the Birdie team so compatibility can be validated during implementation.

  • The API is intended for recordings up to approximately 100 MB.

The multipart request establishes the correlation between the recording and its metadata, and the recording-id uniquely identifies the Audio.

No additional upload, synchronization or correlation step is required from clients.

If the same recording-id is submitted again, the existing record will be updated following the same semantics used by the other ingestion endpoints.

Example request:

curl

    curl https://api.birdie.ai/ingestion/audios/call-123 \
    -H 'Authorization: ApiKey {api-key}' \
    -X PUT \
    -F 'metadata={
            "recorded_at":"2024-01-01T10:00:00Z",
            "kind": {
                "name": "support_ticket",
                "fields": {
                    "subject": "Billing dispute",
                    "status": "solved",
                    "priority": "normal"
                }
            },
            "agent": {
                "id": "agent-123",
                "supervisor_id": "sup-456",
                "company": "acme",
                "team": "customer-support",
                "experience": "1-3 years"
            },
            "additional_fields":{
                "queue":"billing"
            }
        };type=application/json' \
    -F 'file=@call.wav'

Response

A successful request returns:

http

201 Created

This response indicates that the Audio Record was accepted for processing.

It does not indicate that transcription has completed.

Validation Errors

The request will be rejected with:

http

400 Bad Request

if:

• The metadata part is missing.

• The recording part is missing.

• The metadata payload is an invalid JSON.

• Required metadata fields are missing.

Accounts endpoint

PUT /ingestion/audience/accounts/{account-id}

Use to create or update an account. Updates overwrite the entire record (no partial updates).

Example - Match uploaded NPS Feedback

curl

curl https://api.birdie.ai/ingestion/audience/accounts/companyABC \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "name": "Doe Inc.",
    "website": "https://example.com",
    "additional_fields": {
      "key_account": true
    }
  }'

Users endpoint

PUT /ingestion/audience/users/{user-id}

Use to create or update a user. Updates overwrite the entire record (no partial updates).

Example - Match uploaded NPS Feedback

curl

curl https://api.birdie.ai/ingestion/audience/users/john123 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "name": "John Doe",
    "email": "[e-mail]",
    "additional_fields": {
      "key_user": true
    }
  }'

Results If you successfully managed to execute the previous requests, you should see the following results in your Birdie Feed.