Ingest Event | Bigmind

#Overview

Send a single signal event to Bigmind. The event will be validated, associated with the matching CRM record, and queued for AI processing.

#Endpoint

POST /v1/events

POST /v1/events

#Authentication

Include your API key in the Authorization header:

Authorization: Bearer sk_your_api_key_here

Authorization: Bearer sk_your_api_key_here

#Request Body

Field	Type	Required	Description
`signal`	string	Yes	The signal slug (e.g., `visited-documentation-page`)
`version`	number \| "latest"	No	Schema version to use. Defaults to `"latest"`
`identity`	object	Yes	The CRM object this event relates to
`identity.type`	string	Yes	Object type: `account`, `contact`, `deal`, `lead`, or a custom object type
`identity.id`	string	Yes	The object's ID in your CRM (e.g., Salesforce ID, HubSpot ID)
`data`	object	No	Arbitrary JSON payload with event-specific data
`timestamp`	string	No	ISO 8601 timestamp. Defaults to current time if not provided
`reference`	string	No	An optional client-provided identifier echoed back in the response. Useful for correlating requests with results.

#Example Request

curl -X POST https://api.bigmind.ai/v1/events \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "signal": "visited-documentation-page",
    "version": "latest",
    "identity": {
      "type": "account",
      "id": "001ABC000000123"
    },
    "data": {
      "page": "/docs/quickstart",
      "duration_seconds": 120,
      "referrer": "https://google.com"
    },
    "reference": "evt-001"
  }'

curl -X POST https://api.bigmind.ai/v1/events \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "signal": "visited-documentation-page",
    "version": "latest",
    "identity": {
      "type": "account",
      "id": "001ABC000000123"
    },
    "data": {
      "page": "/docs/quickstart",
      "duration_seconds": 120,
      "referrer": "https://google.com"
    },
    "reference": "evt-001"
  }'

#Example Response

{
  "success": true,
  "data": {
    "id": "7871725b-d50d-4cac-ae89-c4c1617767fc",
    "signal_id": "sig_bFyqj0qg",
    "schema_version": null,
    "status": "pending",
    "reference": "evt-001"
  }
}

{
  "success": true,
  "data": {
    "id": "7871725b-d50d-4cac-ae89-c4c1617767fc",
    "signal_id": "sig_bFyqj0qg",
    "schema_version": null,
    "status": "pending",
    "reference": "evt-001"
  }
}

Response Fields

Field	Type	Description
`id`	string	Unique identifier for the ingested event
`signal_id`	string	The internal signal ID that matched the slug
`schema_version`	number \| null	The schema version used, or null if no schema is defined yet
`status`	string	Event processing status: `pending`, `processing`, `completed`, or `failed`
`reference`	string	The client-provided reference, if one was sent

#Rate Limiting

Rate limits vary by signal type:

Signal Type	Rate Limit
Event	100 requests/min per signal
Metric	1,000 requests/min per signal
State	30 requests/min per signal

Rate limit information is included in the response headers:

X-RateLimit-Limit — Maximum requests allowed per minute for this signal
X-RateLimit-Remaining — Requests remaining in the current window
X-RateLimit-Reset — ISO 8601 timestamp when the current rate limit window resets

#Error Responses

400 Bad Request

Returned when required fields are missing.

{
  "success": false,
  "error": "signal is required"
}

{
  "success": false,
  "error": "signal is required"
}

{
  "success": false,
  "error": "identity.type and identity.id are required"
}

{
  "success": false,
  "error": "identity.type and identity.id are required"
}

404 Not Found

Returned when the signal slug does not match any active signal.

{
  "success": false,
  "error": "Signal not found: my-signal-slug"
}

{
  "success": false,
  "error": "Signal not found: my-signal-slug"
}

429 Too Many Requests

Returned when the rate limit is exceeded. Check the X-RateLimit-Reset header for when to retry.

{
  "success": false,
  "error": "Rate limit exceeded"
}

{
  "success": false,
  "error": "Rate limit exceeded"
}