Upserting text is supported only for [indexes with integrated embedding](/guides/index-data-create-an-index#embedding-models); for any other index the request is rejected with `400`. It is not available on BYOC indexes.

A request can contain at most 1000 records. Each record is identified by `_id`. The service also accepts `id` as an alias, which this schema does not model; a record must not carry both.

For guidance, examples, and limits, see [Upsert data](/guides/index-data-upsert-data).

```shell curl theme={null}
# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
INDEX_HOST="INDEX_HOST"
NAMESPACE="YOUR_NAMESPACE"
PINECONE_API_KEY="YOUR_API_KEY"

# Upsert records into a namespace
# `chunk_text` fields are converted to dense vectors
# `category` fields are stored as metadata
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/upsert" \
  -H "Content-Type: application/x-ndjson" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{"_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system"}
      {"_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation"}
      {"_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system"}
      {"_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system"}'
```

`POST /records/namespaces/{namespace}/upsert`

:::code-group
```bash title="cURL"
curl --request POST \
  --url https://{index_host}/records/namespaces/{namespace}/upsert \
  --header 'Authorization: Bearer <token>'
```

```json title="400"
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
  },
  "status": 400
}
```
:::

## Authorizations

- `Authorization` (header, string, required) — Bearer authentication header of the form `Bearer <token>`.

## Path Parameters

- `namespace` (path, string, required) — The namespace to upsert records into.

## Headers

- `X-Pinecone-Api-Version` (header, string, required) — Required date-based version header

## Response

- `201` — A successful response.
- `400` — Bad request. The request body included invalid request parameters.
- `401` — Unauthorized. Possible causes: missing or invalid API key.
- `4XX` — An unexpected error response.
- `5XX` — An unexpected error response.

## Related pages

- [Search with a vector](./database-2026-07-data-plane-query.md)
- [Search with text](./database-2026-07-data-plane-search-records.md)
- [Upsert records](./database-2026-07-data-plane-upsert.md)
- [Fetch records](./database-2026-07-data-plane-fetch.md)
- [Fetch records by metadata](./database-2026-07-data-plane-fetch-by-metadata.md)
- [Update a record](./database-2026-07-data-plane-update.md)
- [Delete records](./database-2026-07-data-plane-delete.md)
- [List record IDs](./database-2026-07-data-plane-list.md)
- [Search with a vector](./database-2026-04-data-plane-query.md)
- [Search with text](./database-2026-04-data-plane-search-records.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.