# API reference overview

You can use the Instacart Developer Platform API to add Instacart shopping capabilities to your website or app. The REST-based API uses predictable, resource-oriented URLs, and standard HTTP methods, response codes, and authentication.

## Request URL[​](#request-url "Direct link to Request URL")

For data privacy and security, API communications use HTTPS. When making a request, be sure to specify `https` in the URL or the request fails.

You receive access to the following domains for requests to the API:

* Development server: `https://connect.dev.instacart.tools`
* Production server: `https://connect.instacart.com`

The following example shows how to structure your request URL:

```
https://connect.instacart.com/idp/v1/<endpoint>
```

## Authentication[​](#authentication "Direct link to Authentication")

You can authenticate your requests for the public endpoints by using an API key. To get a key, contact your Instacart representative.

## Request headers[​](#request-headers "Direct link to Request headers")

HTTP request headers provide contextual information about your API request. For example, you can use headers to specify your preferred response format or provide a secure string for request authentication. Some headers and values are required, while others are optional or required only under certain conditions.

The following table describes the request headers:

| Header          | Required | Description                                                                                                                                                                                                                                    |
| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Accept          |          | The valid content types for the API response payload. Value must be `application/json`.                                                                                                                                                        |
| Accept-Language |          | The preferred natural language for the response payload. Values are `en-US`, `en-CA`, and `fr-CA`. If you don’t provide this header, the system uses the default value for your location: `en-US` for the United States or `en-CA` for Canada. |
| Authorization   | ✅       | The API key provided to you by Instacart, passed as an HTTP `Bearer` token.                                                                                                                                                                    |
| Content-Type    | ✅       | The content type used in the body of the request. Value must be `application/json`.                                                                                                                                                            |

The following example shows a request with all the request headers defined:

```
curl --request POST \

 --url 'https://connect.instacart.com/idp/v1/<endpoint>' \

 --header 'Accept: application/json' \

 --header 'Accept-Language: en-CA' \

 --header 'Authorization: Bearer <API-key>' \

 --header 'Content-Type: application/json' \

 --data '{

<parameters>

}'
```

## Rate limiting[​](#rate-limiting "Direct link to Rate limiting")

The API accepts a limited number of requests per second. Our goal is to accommodate an appropriate volume of legitimate requests while protecting our system against misuse, whether accidental or intentional.

If you receive a `429 Too many requests` error, then your number of requests per second has exceeded the rate limit threshold. Try the request again later. If you repeatedly receive `429` errors, contact your Instacart representative.

## Example languages[​](#example-languages "Direct link to Example languages")

The endpoint documentation typically includes sample requests in the following languages:

* cURL
* Java
* Python
* Go

## Data formats[​](#data-formats "Direct link to Data formats")

The API supports various data types as defined in the [OpenAPI Specification](https://spec.openapis.org/oas/latest.html#data-types). The specification uses the optional modifier property `format` to differentiate between fields of the same type. For example, a `number` field might have a format of `float` or `double`.

### Integer data[​](#integer-data "Direct link to Integer data")

Unless otherwise stated, all `integer` fields support the *int64* format. To ensure that your application can successfully process integer data, you should always interpret `integer` generally to represent any non-fractional, non-decimal number.

### String data[​](#string-data "Direct link to String data")

Unless otherwise stated, all string fields use UTF-8 encoding and do not enforce any length limits.