> ## Documentation Index
> Fetch the complete documentation index at: https://ritika-fa61c43f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CRM Data Pipeline REST API: Complete Endpoint Overview

> Overview of all five REST endpoints exposed by the CRM Data Pipeline server, base URL conventions, and JSON request/response format standards.

The CRM Data Pipeline server is a FastAPI application implementing the [OpenEnv](https://openenv.dev) protocol. It exposes a deterministic REST interface through which an agent submits data engineering actions, receives structured observations, and accumulates rewards across a fully episodic POMDP session. Every request and response is JSON. There is no authentication — the environment is designed as a self-contained benchmark isolated from external systems.

## Base URL

The server binds to port **8080** in all deployment modes.

| Deployment | Base URL |
| - | - |
| Local Docker / bare Python | `http://localhost:8080` |
| HuggingFace Space | `https://<your-space>.hf.space` |

All examples in this reference use `http://localhost:8080`. Substitute your Space URL when running on HuggingFace.

## Verifying the Server

Before running any episode, confirm the server is reachable with the health-check endpoint:

```bash theme={null}
curl http://localhost:8080/
```

A healthy server always returns:

```json theme={null}
{
  "status": "ok",
  "message": "CRM Pipeline Environment is actively running."
}
```

> [!WARNING]
>
> If you receive a connection error, confirm that the Docker container has
> finished starting up and that port 8080 is not already in use on your host.
> The server is started via `uvicorn` bound to `0.0.0.0:8080`.

## Available Endpoints

| Method | Path | Provider | Description |
| - | - | - | - |
| `GET` | `/` | Custom | Health check — confirms server is running |
| `POST` | `/reset` | OpenEnv core | Initialize a new episode and load task data |
| `POST` | `/step` | OpenEnv core | Execute a data engineering action |
| `GET` | `/state` | OpenEnv core | Retrieve current episode state metadata |
| `POST` | `/grader/{episode_id}` | Custom | Score the agent's final DataFrame against ground truth |

> [!NOTE]
>
> The `/reset`, `/step`, and `/state` endpoints are automatically provisioned by
> the **OpenEnv core** `create_fastapi_app` factory. The `/grader/{episode_id}`
> endpoint is a custom addition specific to this environment.

## Request and Response Format

All `POST` endpoints accept and return `application/json`. Set the `Content-Type` header on every `POST` request:

```bash theme={null}
curl -X POST http://localhost:8080/reset \
  -H "Content-Type: application/json" \
  -d '{}'
```

Responses always contain a top-level `observation` object (of type `CRMPipelineObservation`), alongside top-level `reward` and `done` scalar fields that mirror the values inside the observation for convenience.

```json theme={null}
{
  "observation": { "...": "..." },
  "reward": 0.0,
  "done": false
}
```

## Authentication

This environment requires **no authentication**. It is designed as an isolated, single-tenant benchmark. There are no API keys, OAuth tokens, or signed headers. If you expose the server publicly, apply your own network-layer controls.

## Typical Episode Flow

A complete agent run follows this sequence exactly:

```
POST /reset          →  Receive episode_id, task objective, available sources
POST /step (×N)      →  Profile → Standardize → Handle Missing → Deduplicate → …
POST /step           →  SUBMIT_PIPELINE action (requires step_count ≥ 3)
POST /grader/{id}    →  Optional manual scoring call (auto-triggered on submission)
GET  /state          →  Check step_count / episode_id at any point
```

> [!NOTE]
>
> You must call `POST /reset` before any other endpoint. Calling `/step` or
> `/grader` without a prior `/reset` will return a 400 or 404 error because
> no episode context exists in server memory.

## Endpoint Reference Pages

> [card] [POST /reset](https://ritika-fa61c43f.mintlify.site/api/reset.md)
>
> Initialize a fresh episode, load messy CRM data for the configured task,
> and receive the first observation.

> [card] [POST /step](https://ritika-fa61c43f.mintlify.site/api/step.md)
>
> Execute a typed data engineering action — profile, standardize, merge,
> run SQL, deduplicate, or submit.

> [card] [GET /state](https://ritika-fa61c43f.mintlify.site/api/state.md)
>
> Retrieve the current episode UUID, step counter, and active task ID
> without mutating any state.

> [card] [POST /grader/\{episode\_id}](https://ritika-fa61c43f.mintlify.site/api/grader.md)
>
> Compare your agent's final DataFrame against the hidden ground truth
> and receive a normalized score from 0.01 to 0.99.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.