> For the complete documentation index, see [llms.txt](https://docs.conscent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.conscent.ai/events-api-docs.md).

# Events API Docs

### Base URL

The base URL for making requests to the Event Collection API is:

| SANDBOX                                                                                                             | PRODUCTION                                                                                            |
| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [<mark style="color:orange;">https://sandbox-collection.conscent.in</mark>](https://sandbox-collection.conscent.in) | [<mark style="color:orange;">https://collections.conscent.in</mark>](https://collections.conscent.in) |

<details>

<summary>API Endpoints:</summary>

**Endpoint:** `/collect/event`

**Method:** POST

**Description:** The `/collect/event` endpoint is used to collect and store events in the system. Clients can send event data as JSON in the request body. The server will process the incoming event data and store it for further analysis.

**Request Body:**

The request body must contain a JSON object representing the event data. The JSON object can include the following properties:

* <mark style="color:orange;">**`messageBody`**</mark> (\[Event], required): An array containing one or more event objects, each representing an individual event.
* <mark style="color:orange;">**`messageheader`**</mark> (Object, optional): A key-value pair object containing additional headers for the event collection.

```
* Example Request: (HTTP request RAW) *

POST /collect/event HTTP/1.1
Host: example.com
Content-Type: application/json
{
  "messageBody": 
  [
		{
			...properties
		},
		{
			...properties
		}
  ],
  "messageHeaders": 
	        {
		        ...headers
	        }
}
```

**Response:**

* Status Code: 201 OK
* Content-Type: application/json

Example Response:

```json
[
	{
		"headers": {},
		"value": "{\"pingId\": \"c523aa41-9f0f-4fc2-bc96-5a8ff5520b78\"}" 
	}
]
```

</details>

<details>

<summary><strong>Error Handling:</strong></summary>

If there's an issue with the request or the server cannot process the event data, an appropriate error response will be returned.

**Example Error Response:**

```json
{
  "error": "Bad Request",
  "message": "invalid event type",
	"statusCode": 400
}
```

</details>

**Error Codes:**

The API may return various HTTP status codes to indicate the success or failure of a request. Here are some of the common status codes:

<table><thead><tr><th width="240">ERROR CODE</th><th>DESCRIPTION</th></tr></thead><tbody><tr><td><mark style="color:orange;">201 OK</mark></td><td>The request was successful, and the event data was collected.</td></tr><tr><td><mark style="color:orange;">400 Bad Request</mark></td><td>The request was malformed or had invalid parameters.</td></tr><tr><td><mark style="color:orange;">429 Too Many Requests</mark></td><td>The client has exceeded the rate limit for the /collect/event endpoint.</td></tr><tr><td><mark style="color:orange;">500 Internal Server Error</mark></td><td>An unexpected server error occurred.</td></tr></tbody></table>

<details>

<summary><strong>Rate Limits:</strong></summary>

To maintain fair usage and prevent abuse, rate limits are imposed on the /collect/event endpoint. If a client surpasses the permitted number of requests within a specific time window, the API will respond with a rate-limiting error.

**Example Response Headers:**

```
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1672766785
```

</details>

**Rate Limit Headers:**

<table><thead><tr><th width="229">Rate Limit Name</th><th>Description </th></tr></thead><tbody><tr><td><mark style="color:orange;">X-RateLimit-Limit</mark></td><td>The maximum number of requests allowed within the current time window.</td></tr><tr><td><mark style="color:orange;">X-RateLimit-Remaining</mark></td><td>The number of remaining requests allowed within the current time window.</td></tr><tr><td><mark style="color:orange;">X-RateLimit-Reset</mark></td><td>The time at which the rate limit will be reset (usually in UTC timestamp).</td></tr></tbody></table>