Birdie Ingestion API | Birdie Help Center

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}

The response status code will be one of the following:

201 Created on success
400 Bad Request if the request body is invalid
401 Unauthorized if the API key is missing or invalid

For status code 400, the response body will be a JSON object with an error message.

JSON formats

The uploaded data has to be in JSON format. Schema definitions for each type are available at https://api.birdie.ai/ingestion/schemas

For conversations, conversation messages, and feedbacks, the schema includes a kind field that's used to distinguish different kinds of conversations/feedbacks. The value of this field 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 documentated at the URL given above.

There are two fields common to all record types: additional_fields and batch_id.

additional_fields lets clients upload any fields that don't fit the pre-defined schema. These can be mapped to custom fields in Birdie.

batch_id is an optional field that lets clients specify that a set of uploaded records should be grouped together -- in other words, that they're a "batch" of records uploaded together. For example, if a script is used to upload data, the script could generate a batch ID each time it runs and include that batch ID in each record it uploads. The default batch ID includes the current date so all records uploaded on the same day are considered a batch.

Clients that set a batch ID should follow two guidelines: (1) they should upload all records with the same batch ID within 24 hours (2) they should not use a different batch ID for each record (and thus create a huge number of batches).

Endpoints

There are five endpoints to upload different types of data.

PUT /ingestion/conversations/{conversation-id}

This endpoint is used to upload a conversation.

Example request:

curl https://api.birdie.ai/ingestion/conversations/123 \
-X PUT \
-H 'Authorization: ApiKey {api-key}'
-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"
    }
}

The messages belonging to the conversation are uploaded separately.

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

This endpoint is used to upload a message that belongs to a conversation.

Example request:

curl https://api.birdie.ai/ingestion/conversations/123/messages/456 \
-X PUT \
-H 'Authorization: ApiKey {api-key}'
-d '{
    "kind": {
        "fields": {
            "author_id": "author-1",
            "author_name": "John Doe"
        }
    },
    "additional_fields": {
        "high_priority": true
    }
}

The conversation ID must match the ID of a conversation uploaded separately. The order of the uploads is not important -- clients can upload first a conversation, then its messages, or the other way around.

PUT /ingestion/feedbacks/{feedback-id}

This endpoint is used to upload feedbacks that don't belong to a conversation.

Example request:

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

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

This endpoint is used to upload an account.

Example request:

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

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

This endpoint is used to upload a user.

Example request:

curl https://api.birdie.ai/ingestion/audience/users/123 \
-X PUT \
-H 'Authorization: ApiKey {api-key}'
-d '{
    "name": "Jane Doe",
    "email": "[email protected]",
    "additional_fields": {
        "key_account": true
    }
}