# PostHog Capture API 1.0.0

> Update: These endpoints can now be accessed with either your Team API
key or your personal API key.

As explained in our API overview page, PostHog provides two different
APIs.

This page refers to our public endpoints, which use the same API key as
the PostHog snippet. The endpoints documented here are used solely with
POST requests, and will not return any sensitive data from your PostHog
instance.

> Note: For this API, you should use your 'Project API Key' from the
'Project' page in PostHog. This is the same key used in your frontend
snippet.

Note that this specification is an attempt to capture some of the
details on the [POST-only public endpoints
documentation](https://posthog.com/docs/api/post-only-endpoints) but in
a format that we can easily use to validate the correctness of our API
implementation. It is not a complete specification of the API, and
should not be used as such. It will hopefully become such a document,
but is currently a work in progress.

### TODOs

1. add autocapture properties schema
1. add performance event properties schema
1. add session recording event properties schema
1. add any specifications we want to include for other endpoints and GET
   requests e.g. `GET /e/` and `POST /engage/` endpoints.


## Endpoints

### default

#### POST /capture/

Sending an event

> Note: Timestamp is optional. If not set, it'll automatically be set to the current time.

Capture an event. Events are the core of PostHog, and are what you use
to track user behavior, and then analyze and visualize in
PostHog.


`POST /capture/`

### Parameters

#### Query Parameters

* `ip`
  Type: string (ipv4)

* `compression`
  The compression method used to compress the request body.

  Type: string (one of: gzip-js, gzip, lz64)

### Request Body

Content-Type: `application/json`

Schema:
```typescript
undefined
```

Content-Type: `multipart/form-data`

Schema:
```typescript
undefined
```

Content-Type: `text/plain`

### Responses

* **200** OK: On successful capture of an event or events, we notify you with a
200 response. A 200 response guarantees that the event was persisted
by PostHog, but does not guarantee that it will be processed
successfully.


  Content-Type: `application/json`

  Schema:
  ```typescript
  undefined
  ```

* **400** Bad Request: If you send an invalid request, we will return a 400 response. This
can happen if you send an invalid JSON payload among
other things.


  Content-Type: `application/json`

  Schema:
  ```typescript
  undefined
  ```

* **401** Unauthorized: If you send an invalid API key, we will return a 401 response.


  Content-Type: `application/json`

  Schema:
  ```typescript
  undefined
  ```

---

#### POST /batch/

Sending multiple events

You can send multiple events in one go with the Batch API.

There is no limit on the number of events you can send in a
batch, but the entire request body must be less than 20MB by
default (see API overview).

> Note: Timestamp is optional. If not set, it'll automatically
be set to the current time.


`POST /batch/`

### Parameters

#### Query Parameters

* `ip`
  Type: string (ipv4)

* `compression`
  The compression method used to compress the request body.

  Type: string (one of: gzip-js, gzip, lz64)

### Request Body

Content-Type: `application/json`

Schema:
```typescript
undefined
```

Content-Type: `multipart/form-data`

Schema:
```typescript
undefined
```

Content-Type: `text/plain`

### Responses

* **200** OK: On successful capture of an event or events, we notify you with a
200 response. A 200 response guarantees that the event was persisted
by PostHog, but does not guarantee that it will be processed
successfully.


  Content-Type: `application/json`

  Schema:
  ```typescript
  undefined
  ```

* **400** Bad Request: If you send an invalid request, we will return a 400 response. This
can happen if you send an invalid JSON payload among
other things.


  Content-Type: `application/json`

  Schema:
  ```typescript
  undefined
  ```

* **401** Unauthorized: If you send an invalid API key, we will return a 401 response.


  Content-Type: `application/json`

  Schema:
  ```typescript
  undefined
  ```

---

## Models

### Event

```typescript
{
  event: string,
  offset: number,
  distinct_id: string,
  $distinct_id: string,
  $token: string,
  project_id: integer,
  api_key: string,
  timestamp: string (date-time),
  uuid: string (uuid),
  type: string,
  $set: undefined,
  $set_once: undefined,
  properties: {
    $set: undefined,
    $set_once: undefined,
  },
}
```

### SetPersonProperties

```typescript
object
```

### SetOncePersonProperties

```typescript
object
```

### EventCaptureRequest

```typescript
undefined
```

### EventsCaptureRequest

```typescript
undefined
```

### EventsCaptureResponse

```typescript
{
  status: number (one of: 0, 1),
}
```

### EventsCaptureClientErrorResponse

```typescript
{
  type (Required): string (one of: validation_error),
  code (Required): string,
  detail (Required): string,
  attr: string,
}
```

### EventsCaptureUnauthenticatedResponse

```typescript
{
  type (Required): string (one of: authentication_error),
  code (Required): string,
  detail (Required): string,
}
```