> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sellfern.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Agent Integration

> Build Python agents that use Sellfern public V1 APIs safely with scoped API keys.

Python agents can answer user questions and run automations by calling Sellfern's public V1 API from server-side tools. Keep the agent constrained to endpoints and schemas listed in the API Reference.

## Prerequisites

* Python 3.11 or later
* A Sellfern API key with the minimum scopes needed for the user's goal
* An agent framework or model SDK of your choice

## Store configuration

Store secrets in environment variables on the server or automation runner.

```bash theme={null}
export SELLFERN_API_KEY="your_api_key_here"
export SELLFERN_API_URL="https://api.sellfern.com"
```

Do not commit keys, echo them into logs, include them in prompts, or expose them to browser code.

## Make server-side API calls

Your Python tool functions should send the Sellfern API key with the `x-api-key` header.

```python theme={null}
import os
import requests

SELLFERN_API_URL = os.environ.get("SELLFERN_API_URL", "https://api.sellfern.com")
SELLFERN_API_KEY = os.environ["SELLFERN_API_KEY"]


def sellfern_get(path: str, params: dict | None = None) -> dict:
    response = requests.get(
        f"{SELLFERN_API_URL}{path}",
        headers={"x-api-key": SELLFERN_API_KEY},
        params=params,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()
```

Only pass paths that are present in `/api-reference`. If an example or user request asks for a deferred surface, tell the user to confirm endpoint availability in the API Reference before proceeding.

## Design tool definitions safely

When exposing Sellfern actions to an agent:

1. Give each tool one narrow job.
2. Match tool input schemas to the API Reference.
3. Request the minimum scope required for that tool.
4. For write tools, include an `Idempotency-Key` header and reuse it for retries of the same logical mutation.
5. Return Sellfern error codes to the agent without guessing about hidden resources or unsupported endpoints.

## Agent workflow

1. Read `https://docs.sellfern.com/llms.txt` to discover the relevant documentation.
2. Read the product or developer page that explains the user's goal.
3. Confirm the endpoint and schema in `/api-reference`.
4. Call the smallest required Sellfern tool.
5. If Sellfern returns `403 missing_scope`, ask the user for a key with the minimum additional scope.
6. If Sellfern returns `404 not_found`, do not infer that the resource exists in another organization.

## Extending the agent

Before adding a new tool, check the V1 API Reference. Older examples may mention bulk, sync, import, fulfillment, financial, or internal workflows that are not available for public V1. If the endpoint is absent, leave the tool disabled and explain that the user should confirm availability in `/api-reference`.