Skip to main content
POST
/
api
/
v1
/
ingest
curl --request POST \
  --url https://api.evermuse.com/api/v1/ingest \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
[
  {
    "_type": "conversation",
    "_schema_version": "1.0.0",
    "_event_at": "2026-02-24T12:34:56.000Z",
    "_nature": "evidence",
    "_vendor_ids": {
      "conversation_id": "conv-001"
    },
    "_product_id": "prod-abc",
    "_project_ids": [
      "proj-123"
    ],
    "data": {
      "messages": [
        {
          "sender": "agent",
          "text": "How can I help you today?"
        },
        {
          "sender": "customer",
          "text": "I have a question about billing."
        }
      ]
    }
  },
  {
    "_type": "conversation",
    "_schema_version": "1.0.0",
    "_event_at": "2026-02-24T12:40:00.000Z",
    "_nature": "evidence",
    "_vendor_ids": {
      "conversation_id": "conv-002"
    },
    "_product_id": "prod-abc",
    "_project_ids": [
      "proj-123"
    ],
    "data": {
      "messages": [
        {
          "sender": "customer",
          "text": "Can I upgrade my plan?"
        }
      ]
    }
  }
]
'
{
  "batchId": "<string>",
  "acceptedCount": 1,
  "rejectedCount": 1,
  "totalErrorCount": 1,
  "errors": [
    {
      "index": 1,
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.evermuse.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
x-api-key
string
header
required

Your API key, sent as the x-api-key header. Create one in Settings > API Keys with api:write permission. Format: em_sk_...

Headers

​
Idempotency-Key
string

Optional key to prevent duplicate submissions. If a request with the same key and identical body has already been accepted, you'll get back the original response without the data being processed again. Recommended when retrying failed requests.

Maximum string length: 256

Query Parameters

​
format
enum<string>

Optional hint that describes the primary content format of the records. This does not affect validation but helps optimize how your data is processed.

Available options:
text,
audio,
video,
file

Body

​
_type
enum<string>
required

The type of data you're sending. All records in a single batch must share the same type.

  • email_thread — A full email conversation chain (multiple messages grouped together).
  • email — A single email message.
  • meeting_notes — Notes, summaries, or transcripts captured during or after a meeting.
  • call — An audio or video call record (recording url will be provided by the caller in the attachment).
  • call_transcription — A verbatim transcription of a phone or video call.
  • conversation — A multi-turn conversation from chat platforms (e.g. Slack, Intercom, Drift, support tickets).
  • message — A single standalone message (e.g. SMS, or in-app feedback).
Available options:
email_thread,
email,
meeting_notes,
call,
call_transcription,
conversation,
message
​
_schema_version
string
required

Schema version. Use "1.0.0".

Example:

"1.0.0"

​
_event_at
string
required

When the original event occurred, as an ISO-8601 UTC timestamp. Milliseconds are accepted but truncated to second precision.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$
Example:

"2026-02-24T12:34:56Z"

​
_vendor_ids
object
required

One or more IDs from your source system. Must contain at least one entry. Used to prevent duplicates — records with the same _type, _vendor_ids, and _event_at are recognized as the same record and won't be processed twice.

Example:
{ "message_id": "msg-20260224-001" }
​
_nature
enum<string>
required

Classifies how this record should be treated during analysis.

  • evidence — actual customer conversations, meeting notes, support tickets, etc.
  • guidance — internal product team conversations, OKR documents, company goals
  • context — supplementary material used for context but not as a source of customer evidence
Available options:
evidence,
guidance,
context
​
_product_id
string
required

The Evermuse product ID to route records to. Found in Settings > Projects > Actions > Copy in the Evermuse dashboard. All records in a batch must share the same _product_id.

Maximum string length: 128
​
_project_ids
string[]
required

One or more Evermuse project IDs to route records to. Found in Settings > Projects > Actions > Copy in the Evermuse dashboard.

Minimum array length: 1
Maximum string length: 128
​
data
object
required

Your data. Include all relevant fields from your source system. This is stored exactly as you send it.

​
_thread_id
string

Optional ID that groups related records into a thread (e.g., an email chain, a multi-message chat, or a series of related calls). Use the thread or conversation ID from your source system.

Maximum string length: 512
​
_participants
object[]

People involved in the event. Used for attribution and filtering in your Evermuse dashboard.

Maximum array length: 5000
​
_attachments
object[]

Files associated with this record (recordings, documents, images, etc.). Provide a vendor_url for files hosted elsewhere — they will be fetched automatically. Alternatively, use upload_intent_id to reference a file you've already uploaded.

Maximum array length: 10
​
_tags
string[]

Free-form labels for categorization and filtering (e.g., "enterprise", "product-feedback", "q1-2026").

Maximum array length: 200
Maximum string length: 64
​
_pii
object

Optional metadata about personal information in this record. Providing this helps Evermuse handle your data with the right privacy safeguards.

Response

Accepted. Your records have been received and are being processed. Use the returned batchId with GET /api/v1/ingest/batches/{batchId} to check progress.

​
batchId
string
required

Unique identifier for this batch. Use it with GET /api/v1/ingest/batches/{batchId} to check status.

Maximum string length: 128
​
acceptedCount
integer
required

Number of records that passed validation and were accepted.

Required range: x >= 0
​
rejectedCount
integer
required

Number of records that failed validation and were rejected.

Required range: x >= 0
​
totalErrorCount
integer
required

Total number of errors across all rejected records. May be higher than the errors array length since only the first 20 are included.

Required range: x >= 0
​
errors
object[]

Up to 20 errors. The index field refers to the record's position in the batch you sent (starting from 0).

Maximum array length: 20