# Pinecone Python SDK: first working setup

## Install

```
pip install pinecone
```

Use `pip install "pinecone[grpc]"` only if you want the gRPC data client. The plain package is the REST default and is what most agents want.

## Authenticate from the environment

The client reads the `PINECONE_API_KEY` environment variable when you construct it with no arguments. Set the variable in your shell or secret store, never paste a key into code:

```
from pinecone import Pinecone

pc = Pinecone()
```

This is the documented pattern in the SDK README ("or omit and set PINECONE_API_KEY"). Passing a key literal into the constructor is how keys leak into repos and logs.

## Create a serverless index

Index creation is async: the call submits a job, and the index takes a bit to become ready. Always pass a `spec`; omitting it raises `TypeError: Pinecone.create_index() missing 1 required positional argument: 'spec'`.

```
from pinecone import ServerlessSpec

pc.create_index(
    name="quickstart",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
)
```

Match `dimension` to your embedding model (1536 for text-embedding-3-small, 3072 for text-embedding-3-large, 768 for many open models). Dimension and metric are frozen at creation; you cannot change them later, only recreate.

## Get an index handle and write

```
index = pc.Index("quickstart")
index.upsert(vectors=[{"id": "vec1", "values": [0.1, 0.2, 0.3]}])
```

Wrap first writes in try/except on `pinecone.exceptions.PineconeException` so a bad key or wrong dimension surfaces as a readable error instead of a traceback.

## Traps for agents

1. Old tutorials call `pinecone.init(...)`. That was SDK v2. On the current SDK it raises `module 'pinecone' has no attribute 'init'`. The v3+ pattern is `Pinecone()` then `pc.Index(name)`.
2. Creating the index and immediately upserting can hit a not-ready index. Poll `pc.describe_index(name)` until `status.ready` is true before writing (see the index-readiness skill).
3. The free tier caps you at a small number of serverless indexes per project; a 403 on create usually means quota, not a bug in your call.