# Create API Key
Source: https://docs.impulselabs.ai/api-reference/api-keys/create

POST https://api.impulselabs.ai/api/api-keys
Create a new API key for the authenticated user. The raw key is returned once and cannot be retrieved again.

<Note>
  This endpoint uses your dashboard session (Auth0 JWT), not an API key.
</Note>

### Request body

<ParamField type="string">
  A human-readable label for the key. Max 128 characters. Example: `production`, `ci-pipeline`.
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique identifier for the key (UUID). Use this when revoking.
</ResponseField>

<ResponseField name="name" type="string">
  The label you provided.
</ResponseField>

<ResponseField name="key" type="string">
  The raw API key — **shown only once**. Starts with `imp_`.
</ResponseField>

<ResponseField name="key_prefix" type="string">
  First 8 characters of the key. Safe to store and use in logs to identify which key made a request.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -s -X POST "https://api.impulselabs.ai/api/api-keys" \
    -H "Authorization: Bearer <your-dashboard-session-token>" \
    -H "Content-Type: application/json" \
    -d '{ "name": "production" }'
  ```

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

  resp = requests.post(
      "https://api.impulselabs.ai/api/api-keys",
      headers={"Authorization": "Bearer <dashboard-token>"},
      json={"name": "production"},
  )
  data = resp.json()
  print(data["key"])  # Save this — shown once only
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch("https://api.impulselabs.ai/api/api-keys", {
    method: "POST",
    headers: {
      Authorization: "Bearer <dashboard-token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "production" }),
  });
  const { key } = await resp.json();
  console.log(key); // imp_a1b2c3...
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "production",
    "key": "imp_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "key_prefix": "imp_a1b2",
    "created_at": "2026-02-19T12:00:00.000Z"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "Invalid body",
    "details": {
      "fieldErrors": { "name": ["String must contain at least 1 character(s)"] }
    }
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "error": "Upgrade required",
    "message": "API keys are available on Pro plans and above. Upgrade at /billing."
  }
  ```
</ResponseExample>


# List API Keys
Source: https://docs.impulselabs.ai/api-reference/api-keys/list

GET https://api.impulselabs.ai/api/api-keys
List all API keys for the authenticated user. Raw key values are never returned — only metadata.

<Note>
  This endpoint uses your dashboard session (Auth0 JWT), not an API key.
</Note>

### Response

Returns an array of key objects ordered by `created_at` descending.

<ResponseField name="id" type="string">
  Unique key identifier. Use this when revoking.
</ResponseField>

<ResponseField name="name" type="string">
  The label assigned when the key was created.
</ResponseField>

<ResponseField name="key_prefix" type="string">
  First 8 characters of the key. Useful for identifying a key in logs.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="last_used_at" type="string | null">
  ISO 8601 timestamp of the most recent validated request, or `null` if the key has never been used.
</ResponseField>

<ResponseField name="request_count" type="number">
  Total number of validated requests made with this key.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -s "https://api.impulselabs.ai/api/api-keys" \
    -H "Authorization: Bearer <your-dashboard-session-token>"
  ```

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

  resp = requests.get(
      "https://api.impulselabs.ai/api/api-keys",
      headers={"Authorization": "Bearer <dashboard-token>"},
  )
  print(resp.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "production",
      "key_prefix": "imp_a1b2",
      "created_at": "2026-02-19T12:00:00.000Z",
      "last_used_at": "2026-02-19T14:32:11.000Z",
      "request_count": 47
    },
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "name": "ci-pipeline",
      "key_prefix": "imp_c3d4",
      "created_at": "2026-01-10T09:15:00.000Z",
      "last_used_at": null,
      "request_count": 0
    }
  ]
  ```
</ResponseExample>


# Revoke API Key
Source: https://docs.impulselabs.ai/api-reference/api-keys/revoke

DELETE https://api.impulselabs.ai/api/api-keys/{id}
Permanently revoke an API key. Any requests using the revoked key will immediately return 401.

<Warning>
  This action is irreversible. The key is deleted along with its usage log. Create a replacement key before revoking a key that is actively in use.
</Warning>

<Note>
  This endpoint uses your dashboard session (Auth0 JWT), not an API key.
</Note>

### Path parameters

<ParamField type="string">
  The UUID of the key to revoke. Obtain this from [List API Keys](/api-reference/api-keys/list).
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  `true` when the key has been deleted.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -s -X DELETE "https://api.impulselabs.ai/api/api-keys/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
    -H "Authorization: Bearer <your-dashboard-session-token>"
  ```

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

  key_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  resp = requests.delete(
      f"https://api.impulselabs.ai/api/api-keys/{key_id}",
      headers={"Authorization": "Bearer <dashboard-token>"},
  )
  print(resp.json())  # {"success": true}
  ```

  ```javascript Node.js theme={null}
  const keyId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
  const resp = await fetch(
    `https://api.impulselabs.ai/api/api-keys/${keyId}`,
    {
      method: "DELETE",
      headers: { Authorization: "Bearer <dashboard-token>" },
    }
  );
  const { success } = await resp.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "API key not found"
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "error": "Forbidden"
  }
  ```
</ResponseExample>


# Errors
Source: https://docs.impulselabs.ai/api-reference/errors

HTTP status codes and error response shapes returned by the Impulse Labs API

All error responses return JSON with at least an `error` or `detail` field.

## Error response shape

```json theme={null}
{
  "error": "Human-readable error message",
  "detail": "Additional context (FastAPI endpoints)"
}
```

## HTTP status codes

| Code  | Meaning               | Common causes                                                               |
| ----- | --------------------- | --------------------------------------------------------------------------- |
| `400` | Bad Request           | Missing required fields, invalid JSON, schema validation failure            |
| `401` | Unauthorized          | Missing `Authorization` header, invalid or revoked API key                  |
| `403` | Forbidden             | Attempting to access another user's resource; plan does not permit API keys |
| `404` | Not Found             | Deployment ID does not exist for your account                               |
| `409` | Conflict              | A deployment with that ID already exists                                    |
| `429` | Too Many Requests     | Rate limit exceeded for your plan tier                                      |
| `500` | Internal Server Error | Unexpected server-side error                                                |
| `503` | Service Unavailable   | Model container is not yet active or is temporarily unreachable             |

## Error examples

### 401 — Invalid API key

```json theme={null}
{
  "valid": false,
  "error": "Invalid API key"
}
```

The key is missing, malformed, or has been revoked. Double-check the `Authorization` header.

### 403 — Plan upgrade required

```json theme={null}
{
  "error": "Upgrade required",
  "message": "API keys are available on Pro plans and above. Upgrade at /billing."
}
```

### 404 — Deployment not found

```json theme={null}
{
  "detail": "No deployment 'my-model' found for user"
}
```

The `deployment_id` either does not exist or belongs to a different user.

### 409 — Duplicate deployment

```json theme={null}
{
  "detail": "Deployment 'my-model' already exists"
}
```

### 429 — Rate limit exceeded

```json theme={null}
{
  "valid": false,
  "error": "Rate limit exceeded",
  "limit": 120,
  "retry_after_seconds": 34
}
```

Wait the number of seconds in `retry_after_seconds` before retrying. See also the `Retry-After` response header.

### 503 — Deployment not active

```json theme={null}
{
  "detail": "Deployment 'my-model' is not active (status: BUILDING)"
}
```

The model container is still starting up. [Check the status](/api-reference/inference/status) and retry when `ACTIVE`.

### 503 — Container unreachable

```json theme={null}
{
  "detail": "Deployment 'my-model' is not reachable. Retry shortly"
}
```

The container is registered as `ACTIVE` but did not respond. Usually resolves within seconds — retry with exponential backoff.

## Handling errors — recommended pattern

```python Python theme={null}
import os, time, requests

def infer_with_retry(deployment_id: str, inputs: dict, max_retries: int = 3) -> dict:
    url = "https://inference.impulselabs.ai/infer"
    headers = {
        "Authorization": f"Bearer {os.environ['IMPULSE_API_KEY']}",
        "Content-Type": "application/json",
    }
    payload = {"deployment_id": deployment_id, "inputs": inputs}

    for attempt in range(max_retries):
        resp = requests.post(url, headers=headers, json=payload)

        if resp.status_code == 200:
            return resp.json()

        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 5))
            print(f"Rate limited — waiting {retry_after}s")
            time.sleep(retry_after)
            continue

        if resp.status_code in (502, 503):
            wait = 2 ** attempt
            print(f"Service unavailable — retrying in {wait}s")
            time.sleep(wait)
            continue

        # Non-retryable error
        resp.raise_for_status()

    raise RuntimeError(f"Failed after {max_retries} attempts")
```

```javascript Node.js theme={null}
async function inferWithRetry(deploymentId, inputs, maxRetries = 3) {
  const url = "https://inference.impulselabs.ai/infer";

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const resp = await fetch(url, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.IMPULSE_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ deployment_id: deploymentId, inputs }),
    });

    if (resp.ok) return resp.json();

    if (resp.status === 429) {
      const retryAfter = parseInt(resp.headers.get("Retry-After") ?? "5", 10);
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      continue;
    }

    if (resp.status === 503 || resp.status === 502) {
      await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
      continue;
    }

    const body = await resp.json().catch(() => ({}));
    throw Object.assign(new Error(body.detail ?? body.error ?? "Request failed"), { status: resp.status });
  }

  throw new Error(`Failed after ${maxRetries} attempts`);
}
```


# Run Inference
Source: https://docs.impulselabs.ai/api-reference/inference/run

POST https://inference.impulselabs.ai/infer
Send input features to a deployed model and receive a prediction. The model container must be in ACTIVE status.

### Authentication

Pass your `imp_` API key as a Bearer token:

```
Authorization: Bearer imp_your_key_here
```

Your `user_id` is resolved server-side from the key — do not include it in the request body.

### Request body

<ParamField type="string">
  The ID of the deployed model to call. Find this on the **Models** page in the dashboard.

  Example: `clf-titanic-survived`
</ParamField>

<ParamField type="object">
  A JSON object mapping feature column names to their values, exactly as they appear in the training dataset.

  ```json theme={null}
  {
    "Pclass": 3,
    "Sex": "male",
    "Age": 22,
    "Fare": 7.25
  }
  ```
</ParamField>

### Response

<ResponseField name="prediction" type="any">
  The model's output. For classification models this is the predicted class label (e.g. `0` or `"yes"`). For regression models it is a numeric value.
</ResponseField>

<ResponseField name="probability" type="number | null">
  Confidence score between `0` and `1` for the predicted class. Present for classification models, `null` for regression.
</ResponseField>

<ResponseField name="target" type="string | null">
  The name of the target column the model was trained to predict.
</ResponseField>

### Rate limit headers

Every response includes standard rate-limit headers:

| Header                  | Description                                      |
| ----------------------- | ------------------------------------------------ |
| `X-RateLimit-Limit`     | Requests allowed in the current 60-second window |
| `X-RateLimit-Remaining` | Requests remaining in the current window         |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets            |
| `Retry-After`           | Seconds to wait before retrying (only on `429`)  |

<RequestExample>
  ```bash cURL — Titanic survival prediction theme={null}
  curl -s -X POST "https://inference.impulselabs.ai/infer" \
    -H "Authorization: Bearer $IMPULSE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "deployment_id": "clf-titanic-survived",
      "inputs": {
        "Pclass": 3,
        "Sex": "male",
        "Age": 22,
        "SibSp": 1,
        "Parch": 0,
        "Fare": 7.25,
        "Embarked": "S"
      }
    }'
  ```

  ```bash cURL — Customer churn prediction theme={null}
  curl -s -X POST "https://inference.impulselabs.ai/infer" \
    -H "Authorization: Bearer $IMPULSE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "deployment_id": "clf-churn-v2",
      "inputs": {
        "tenure": 12,
        "MonthlyCharges": 65.5,
        "TotalCharges": 786.0,
        "Contract": "Month-to-month",
        "PaymentMethod": "Electronic check",
        "InternetService": "Fiber optic"
      }
    }'
  ```

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

  resp = requests.post(
      "https://inference.impulselabs.ai/infer",
      headers={
          "Authorization": f"Bearer {os.environ['IMPULSE_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "deployment_id": "clf-titanic-survived",
          "inputs": {
              "Pclass": 3,
              "Sex": "male",
              "Age": 22,
              "SibSp": 1,
              "Parch": 0,
              "Fare": 7.25,
              "Embarked": "S",
          },
      },
  )
  resp.raise_for_status()
  result = resp.json()
  print(f"Prediction: {result['prediction']}, probability: {result['probability']:.0%}")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://inference.impulselabs.ai/infer", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.IMPULSE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      deployment_id: "clf-titanic-survived",
      inputs: {
        Pclass: 3,
        Sex: "male",
        Age: 22,
        SibSp: 1,
        Parch: 0,
        Fare: 7.25,
        Embarked: "S",
      },
    }),
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.detail ?? "Inference failed");
  }

  const { prediction, probability, target } = await response.json();
  console.log(`${target}: ${prediction} (${(probability * 100).toFixed(1)}%)`);
  ```

  ```typescript TypeScript theme={null}
  interface InferRequest {
    deployment_id: string;
    inputs: Record<string, unknown>;
  }

  interface InferResponse {
    prediction: unknown;
    probability: number | null;
    target: string | null;
  }

  async function infer(deploymentId: string, inputs: Record<string, unknown>): Promise<InferResponse> {
    const resp = await fetch("https://inference.impulselabs.ai/infer", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.IMPULSE_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ deployment_id: deploymentId, inputs } satisfies InferRequest),
    });

    if (!resp.ok) {
      const err = await resp.json();
      throw Object.assign(new Error(err.detail ?? "Inference failed"), { status: resp.status });
    }

    return resp.json() as Promise<InferResponse>;
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK — Classification theme={null}
  {
    "prediction": 0,
    "probability": 0.142,
    "target": "Survived"
  }
  ```

  ```json 200 OK — Regression theme={null}
  {
    "prediction": 42350.75,
    "probability": null,
    "target": "SalePrice"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "valid": false,
    "error": "Invalid API key"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "detail": "No deployment 'clf-titanic-survived' found for user"
  }
  ```

  ```json 429 Too Many Requests theme={null}
  {
    "valid": false,
    "error": "Rate limit exceeded",
    "limit": 120,
    "retry_after_seconds": 34
  }
  ```

  ```json 503 Service Unavailable — model not ready theme={null}
  {
    "detail": "Deployment 'clf-titanic-survived' is not active (status: BUILDING)"
  }
  ```

  ```json 503 Service Unavailable — container unreachable theme={null}
  {
    "detail": "Deployment 'clf-titanic-survived' is not reachable. Retry shortly"
  }
  ```
</ResponseExample>


# Deployment Status
Source: https://docs.impulselabs.ai/api-reference/inference/status

GET https://inference.impulselabs.ai/deploy/status
Check whether a model deployment is ready to receive inference requests.

Poll this endpoint to confirm a deployment is `ACTIVE` before sending inference requests.

### Query parameters

<ParamField type="string">
  The deployment ID of the model. Found on the **Models** page in the dashboard.
</ParamField>

### Response

<ResponseField name="deployment_id" type="string">
  Echoes the requested deployment ID.
</ResponseField>

<ResponseField name="status" type="string">
  Current lifecycle status. See the table below.
</ResponseField>

### Deployment statuses

| Status     | Description                                            |
| ---------- | ------------------------------------------------------ |
| `CREATED`  | Deployment registered; container build not yet started |
| `BUILDING` | Container image is being built                         |
| `ACTIVE`   | Model is deployed and accepting inference requests     |
| `FAILED`   | Deployment failed — retrain or contact support         |

<Info>
  Cold-start latency is typically under 30 seconds. If a deployment stays in `BUILDING` for more than 5 minutes, try redeploying from the dashboard.
</Info>

### Polling example

```python Python — wait for ACTIVE theme={null}
import os
import time
import requests

API_KEY = os.environ["IMPULSE_API_KEY"]
DEPLOYMENT_ID = "clf-titanic-survived"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def wait_for_active(deployment_id: str, timeout: int = 120) -> None:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            "https://inference.impulselabs.ai/deploy/status",
            params={"deployment_id": deployment_id},
            headers=HEADERS,
        )
        resp.raise_for_status()
        status = resp.json()["status"]
        print(f"Status: {status}")
        if status == "ACTIVE":
            return
        if status == "FAILED":
            raise RuntimeError(f"Deployment {deployment_id} failed")
        time.sleep(5)
    raise TimeoutError(f"Deployment did not become ACTIVE within {timeout}s")

wait_for_active(DEPLOYMENT_ID)
```

<RequestExample>
  ```bash cURL theme={null}
  curl -s "https://inference.impulselabs.ai/deploy/status?deployment_id=clf-titanic-survived" \
    -H "Authorization: Bearer $IMPULSE_API_KEY"
  ```

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

  resp = requests.get(
      "https://inference.impulselabs.ai/deploy/status",
      params={"deployment_id": "clf-titanic-survived"},
      headers={"Authorization": f"Bearer {os.environ['IMPULSE_API_KEY']}"},
  )
  print(resp.json()["status"])  # "ACTIVE"
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({ deployment_id: "clf-titanic-survived" });
  const resp = await fetch(
    `https://inference.impulselabs.ai/deploy/status?${params}`,
    { headers: { Authorization: `Bearer ${process.env.IMPULSE_API_KEY}` } }
  );
  const { status } = await resp.json();
  console.log(status); // "ACTIVE"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK — Active theme={null}
  {
    "deployment_id": "clf-titanic-survived",
    "status": "ACTIVE"
  }
  ```

  ```json 200 OK — Still building theme={null}
  {
    "deployment_id": "clf-titanic-survived",
    "status": "BUILDING"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "detail": "No deployment 'clf-titanic-survived' found for user"
  }
  ```
</ResponseExample>


# Rate Limits
Source: https://docs.impulselabs.ai/api-reference/rate-limits

Per-plan request limits and how to handle 429 responses

The Impulse Labs API enforces a **sliding window rate limit** per user per 60-second period.

## Limits by plan

| Plan       | Requests / 60 seconds |
| ---------- | :-------------------: |
| Pro        |          120          |
| Team       |          300          |
| Enterprise |         1 000         |

<Note>
  Limits apply to **validated inference requests** — each call to `POST /infer` counts as one request against your limit.
</Note>

## Rate limit headers

Every response from `POST /infer` includes these headers:

| Header                  | Type    | Description                                           |
| ----------------------- | ------- | ----------------------------------------------------- |
| `X-RateLimit-Limit`     | integer | Maximum requests allowed in the window                |
| `X-RateLimit-Remaining` | integer | Requests remaining in the current window              |
| `X-RateLimit-Reset`     | integer | Unix timestamp (seconds) when the window resets       |
| `Retry-After`           | integer | Seconds to wait (**only present on `429` responses**) |

### Reading headers

```bash theme={null}
curl -si -X POST "https://inference.impulselabs.ai/infer" \
  -H "Authorization: Bearer $IMPULSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deployment_id": "my-model", "inputs": {}}' \
  | grep -i x-ratelimit

# X-RateLimit-Limit: 120
# X-RateLimit-Remaining: 118
# X-RateLimit-Reset: 1708346460
```

## Handling 429 Too Many Requests

When you exceed the limit, the API returns:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 34
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708346460
```

```json theme={null}
{
  "valid": false,
  "error": "Rate limit exceeded",
  "limit": 120,
  "retry_after_seconds": 34
}
```

### Recommended retry strategy

1. Read the `Retry-After` header and wait that many seconds before retrying.
2. Do not retry immediately in a tight loop — this will keep triggering the limit.
3. For batch workloads, spread requests over time or use exponential backoff.

```python Python — respect Retry-After theme={null}
import time, requests

def safe_infer(session, payload, headers):
    while True:
        resp = session.post(
            "https://inference.impulselabs.ai/infer",
            json=payload,
            headers=headers,
        )
        if resp.status_code == 429:
            wait = int(resp.headers.get("Retry-After", 5))
            print(f"Rate limited. Retrying in {wait}s...")
            time.sleep(wait)
            continue
        resp.raise_for_status()
        return resp.json()
```

## Upgrading your plan

If you consistently hit rate limits, consider upgrading to a higher plan at [app.impulselabs.ai/billing](https://app.impulselabs.ai/billing).

For custom limits or Enterprise pricing, [contact us](mailto:hello@impulselabs.ai).


# Authentication
Source: https://docs.impulselabs.ai/authentication

Authenticate API requests with an Impulse Labs API key

All requests to the Inference API must include a valid API key in the `Authorization` header.

## API key format

Impulse Labs API keys start with `imp_` followed by 64 hex characters:

```
imp_a1b2c3d4e5f6...  (68 characters total)
```

## Sending your key

Pass the key as a **Bearer token** in the `Authorization` header on every request:

```bash theme={null}
curl https://inference.impulselabs.ai/infer \
  -H "Authorization: Bearer imp_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

<Warning>
  Never include your API key in client-side code, URLs, or version control. Use environment variables or a secrets manager.
</Warning>

## Creating an API key

<Steps>
  <Step title="Open the dashboard">
    Go to [app.impulselabs.ai](https://app.impulselabs.ai) and sign in.
  </Step>

  <Step title="Navigate to API Keys">
    Click your avatar → **Settings** → **API Keys**.
  </Step>

  <Step title="Create a key">
    Click **New API Key**, enter a descriptive name (e.g. `production`, `ci-pipeline`), and click **Create**.
  </Step>

  <Step title="Copy and store the key">
    The raw key is shown **only once**. Copy it and store it in a secure location such as your hosting provider's secret store or a `.env` file that is not committed to version control.
  </Step>
</Steps>

<Note>
  API keys require a **Pro, Team, or Enterprise** plan. If you see a `403 Upgrade required` response, visit [app.impulselabs.ai/billing](https://app.impulselabs.ai/billing).
</Note>

## Revoking a key

You can revoke a key at any time from the **Settings → API Keys** page in the dashboard, or via the [Revoke API Key](/api-reference/api-keys/revoke) endpoint. Revoked keys are rejected immediately with a `401` response.

## Key security best practices

* Rotate keys regularly and revoke any you no longer use.
* Create separate keys for each application or environment.
* Never log the raw key — use the `key_prefix` (first 8 characters) for identifying which key was used in logs.
* Set up monitoring on your usage metrics in the dashboard to detect unexpected spikes.


# Use Impulse with Claude
Source: https://docs.impulselabs.ai/claude

Connect Claude Desktop or Claude Code to the Impulse MCP server and train, inspect, deploy, and run models from Claude

Claude can use Impulse through the Model Context Protocol (MCP). Once connected, Claude can upload datasets, start training sessions, inspect artifacts, deploy models, and run predictions through the Impulse tools.

This guide covers both Claude Desktop (connector) and Claude Code (terminal). For direct REST API calls, see the [Quickstart](/quickstart).

## Requirements

* Claude Desktop or the Claude Code CLI.
* An Impulse account. An API key is optional — guest mode works without one, but sign in with a key for authenticated workflows tied to your account.

<Note>
  Impulse connects to the hosted production gateway (`https://api.impulselabs.ai`) by default. You don't need to run anything yourself.
</Note>

## Claude Desktop

### Add Impulse as a connector (recommended)

The most reliable way to use Impulse in Claude Desktop is as a remote connector — it's a plain HTTP connection, so there's no local process for Claude Desktop to manage.

<Steps>
  <Step title="Open Connectors settings">
    In Claude Desktop, go to **Settings > Connectors > Add custom connector**.
  </Step>

  <Step title="Enter the server details">
    Name it `Impulse` and set the URL to `https://api.impulselabs.ai/api/mcp-http`.
  </Step>

  <Step title="Connect">
    Click **Connect**. Your browser opens to sign in (or sign up) via Impulse — no manual API key needed. Approve access and you'll be redirected back to Claude, now authenticated.
  </Step>

  <Step title="Enable it for a conversation">
    Connectors can also be toggled per chat via **+ > Connectors** inside a conversation. Make sure Impulse is on there too, not just in Settings.
  </Step>
</Steps>

<Note>
  Datasets: ask Claude to upload the file with `impulse_dataset_upload_base64` (Claude reads the file itself and sends the contents inline). The local-path upload tool described below isn't available over this connector — a remote server can't read a path on your machine.
</Note>

### One-click extension (`.mcpb`, optional)

Claude Desktop also supports installing Impulse as a local extension package. This gives Claude direct access to your filesystem (so it can upload a dataset by local path), but the extension runs as a local process that Claude Desktop has to spawn and manage per conversation — in practice this has been less reliable than the connector above, with tools sometimes reporting "disabled" or fully disconnecting mid-conversation. Use this only if you specifically need local-path dataset uploads.

<Steps>
  <Step title="Download the extension">
    Download [impulse-mcp.mcpb](https://github.com/impulse-ai/impulse-mcp-plugin/releases/latest/download/impulse-mcp.mcpb) from the latest release.
  </Step>

  <Step title="Install it">
    Double-click the downloaded file, or open Claude Desktop's **Settings > Extensions**, and drag the file onto the page.
  </Step>

  <Step title="Configure (optional)">
    Open the Impulse extension's **Configure** panel to add an API key for authenticated access. Leave it blank to use guest mode.
  </Step>

  <Step title="Enable it">
    Make sure the extension is turned on in **Settings > Extensions**, and also enabled for the specific conversation via **+ > Connectors**, then start a new conversation.
  </Step>
</Steps>

## Claude Code

Register Impulse as an MCP server from the terminal.

```bash theme={null}
claude mcp add --transport http impulse https://api.impulselabs.ai/api/mcp-http \
  --header "x-api-key: <your Impulse API key>" \
  --header "x-impulse-client-surface: claude_code"
```

The `x-api-key` header is optional — omit it to use guest mode. `x-impulse-client-surface` is optional too; it doesn't affect auth, it just tags usage so it's attributed to Claude Code rather than lumped in as `unknown` in your `impulse_usage_summary` breakdown.

By default this registers the server at **local** scope (this project only). Add `-s user` to make it available in every project:

```bash theme={null}
claude mcp add -s user --transport http impulse https://api.impulselabs.ai/api/mcp-http \
  --header "x-api-key: <your Impulse API key>" \
  --header "x-impulse-client-surface: claude_code"
```

Verify it's connected:

```bash theme={null}
claude mcp list
```

You should see `impulse` listed as `✔ Connected`. To check whether it picked up your API key:

```bash theme={null}
claude -p "Call the impulse_auth_status tool and report the result." --allowedTools "mcp__impulse__impulse_auth_status"
```

<Note>
  `--allowedTools` is only needed for non-interactive (`-p`) runs like the check above. In a normal interactive `claude` session, Claude will prompt you to approve Impulse tools the first time it calls one, and you can choose "always allow." To skip the prompt permanently, add `"mcp__impulse__*"` to `permissions.allow` in `.claude/settings.json`.
</Note>

```json .claude/settings.json theme={null}
{
  "permissions": {
    "allow": [
      "mcp__impulse__*"
    ]
  }
}
```

## First prompt

After connecting, ask Claude to use Impulse:

```text theme={null}
Use the Impulse MCP server to train a model from my uploaded dataset. Show me the session id, required artifacts, metrics, and prediction file when the run is complete.
```

If you already have dataset IDs:

```text theme={null}
Use Impulse MCP. Train a tabular classification model with dataset_id=<TRAIN_DATASET_ID> and test_dataset_id=<TEST_DATASET_ID>. The target column is Transported. Produce submission.csv and save the canonical model artifacts.
```

## What Claude can do

Once connected, Claude can use Impulse MCP tools to:

* Upload datasets.
* List datasets and projects.
* Start training sessions.
* Poll session status.
* Inspect generated artifacts.
* Package models for inference.
* Deploy trained models.
* Fetch deployment feature contracts.
* Run predictions against deployed models.

## Troubleshooting

### `impulse_auth_status` reports guest mode even though you set an API key

Check what's actually registered:

```bash theme={null}
claude mcp get impulse
```

Confirm the `x-api-key` header shows your raw key with no `Bearer ` prefix — Impulse's API key auth expects the raw key value, not an `Authorization`-style scheme. If it's wrong, remove and re-add:

```bash theme={null}
claude mcp remove impulse -s local
claude mcp add -s local --transport http impulse https://api.impulselabs.ai/api/mcp-http \
  --header "x-api-key: <your Impulse API key>" \
  --header "x-impulse-client-surface: claude_code"
```

### Claude Code doesn't show Impulse tools

Check the server list:

```bash theme={null}
claude mcp list
```

If `impulse` is missing or not connected, re-add it with the command above, then start a new session.

### The `.mcpb` file won't open in Claude Desktop's install picker

Some macOS file pickers filter by registered file type and may not recognize `.mcpb`. Double-click the downloaded file directly, or drag it onto **Settings > Extensions**, instead of using the picker's "choose file" dialog.

### The `.mcpb` extension says a tool is "disabled" or disconnects mid-conversation

This is a per-chat toggle issue, not your account or the extension itself: Claude Desktop lets you enable/disable each connector (including installed `.mcpb` extensions) per conversation via **+ > Connectors**, separate from the global toggle in **Settings > Extensions**. If that per-chat toggle is off, tool calls get rejected and Claude may describe it as "disabled." Turn it on for that conversation and retry.

If it still shows fully disconnected afterward, the local extension process likely needs a clean restart — start a new conversation rather than continuing the same one. This local-process instability is why the [connector](#add-impulse-as-a-connector-recommended) is the recommended way to use Impulse in Claude Desktop.


# Use Impulse with Codex
Source: https://docs.impulselabs.ai/codex

Connect Codex to the Impulse MCP server and train, inspect, deploy, and run models from Codex

Codex can use Impulse through the Model Context Protocol (MCP). Once connected, Codex can upload datasets, start training sessions, inspect artifacts, deploy models, and run predictions through the Impulse tools.

This guide is for Codex only. For direct REST API calls, see the [Quickstart](/quickstart).

## Requirements

* A Codex app or Codex CLI install.
* An Impulse account with access to the production dashboard.
* A browser session that can sign in to Impulse during MCP OAuth.

<Note>
  You do not need to copy an Impulse API key into Codex when using the OAuth MCP setup below. Codex stores the MCP server config locally and completes auth through your browser.
</Note>

## Connect Codex from settings

The Codex app, CLI, and IDE extension share MCP settings. If you connect Impulse in one Codex surface, the others can use the same server because the configuration is stored in `config.toml`.

<Steps>
  <Step title="Open Codex settings">
    In the Codex app, open **Settings** from the app menu or press **Cmd+,** on macOS.
  </Step>

  <Step title="Open Integrations & MCP">
    Go to **Integrations & MCP**. This is where Codex manages external MCP servers.
  </Step>

  <Step title="Add a custom MCP server">
    Choose the option to add your own MCP server.
  </Step>

  <Step title="Enter the server details">
    Use `impulse` as the server name and `https://api.impulselabs.ai/api/mcp-http` as the server URL.
  </Step>

  <Step title="Authenticate">
    If Codex prompts for OAuth, continue in the browser, sign in to Impulse, approve access, and return to Codex.
  </Step>

  <Step title="Start a new thread">
    Open a new Codex thread and ask Codex to use Impulse.
  </Step>
</Steps>

## Connect Codex from the CLI

If you prefer terminal setup, add the same production Impulse MCP server with the Codex CLI:

```bash theme={null}
codex mcp add impulse --url https://api.impulselabs.ai/api/mcp-http
```

Start the OAuth login:

```bash theme={null}
codex mcp login impulse
```

Your browser will open. Sign in to Impulse, approve access, and return to Codex when the flow completes.

Verify the server is configured:

```bash theme={null}
codex mcp list
```

In an interactive Codex session, you can also run:

```text theme={null}
/mcp
```

You should see an `impulse` MCP server with available Impulse tools.

## Optional local config

Codex stores MCP servers in `~/.codex/config.toml`. The CLI command above writes a config similar to:

```toml theme={null}
[mcp_servers.impulse]
url = "https://api.impulselabs.ai/api/mcp-http"
```

For a repo-specific setup, put the same block in `.codex/config.toml` inside a trusted project.

## First Codex prompt

After auth, start a new Codex thread and ask it to use Impulse:

```text theme={null}
Use the Impulse MCP server to train a model from my uploaded dataset. Show me the session id, required artifacts, metrics, and prediction file when the run is complete.
```

If you already have dataset IDs:

```text theme={null}
Use Impulse MCP. Train a tabular classification model with dataset_id=<TRAIN_DATASET_ID> and test_dataset_id=<TEST_DATASET_ID>. The target column is Transported. Produce submission.csv and save the canonical model artifacts.
```

## What Codex can do

Once connected, Codex can use Impulse MCP tools to:

* Upload datasets.
* List datasets and projects.
* Start training sessions.
* Poll session status.
* Inspect generated artifacts.
* Package models for inference.
* Deploy trained models.
* Fetch deployment feature contracts.
* Run predictions against deployed models.

## Troubleshooting

### Codex says the server is not authenticated

Run the login command again:

```bash theme={null}
codex mcp login impulse
```

Then start a new Codex thread. New MCP auth and tool availability are easiest to verify in a fresh thread.

### The OAuth callback fails

Make sure the production Impulse Auth0 application allows the callback URL used by Codex. Codex may use a localhost callback URL by default unless you configure a custom callback URL.

### Codex does not show Impulse tools

Check the server list:

```bash theme={null}
codex mcp list
```

If the server is missing, add it again:

```bash theme={null}
codex mcp add impulse --url https://api.impulselabs.ai/api/mcp-http
codex mcp login impulse
```

Then restart Codex or open a new thread.


# Introduction
Source: https://docs.impulselabs.ai/introduction

Use models you train in the Impulse AI dashboard via a simple REST API

## What is the Impulse AI API?

The Impulse AI API lets you train machine-learning models in the dashboard — no code required — then call them programmatically from any application using a standard REST API.

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get your first inference in under 5 minutes
  </Card>

  <Card title="Use with Codex" icon="terminal" href="/codex">
    Connect Codex to Impulse MCP
  </Card>

  <Card title="Use with Claude" icon="terminal" href="/claude">
    Connect Claude Desktop or Claude Code to Impulse MCP
  </Card>

  <Card title="Run Inference" icon="bolt" href="/api-reference/inference/run">
    Send inputs to your deployed model
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Create and manage API keys
  </Card>

  <Card title="Error Reference" icon="circle-exclamation" href="/api-reference/errors">
    Understand error codes and responses
  </Card>
</CardGroup>

## Base URLs

| Environment | URL                                |
| ----------- | ---------------------------------- |
| Production  | `https://api.impulselabs.ai`       |
| Inference   | `https://inference.impulselabs.ai` |

## How it works

1. **Train** - Upload a dataset and train a model in the [dashboard](https://app.impulselabs.ai), or connect [Codex to Impulse MCP](/codex) and ask Codex to run the workflow. Each deployed model gets a `deployment_id`.
2. **Create an API key** - Go to **Settings -> API Keys** in the dashboard and generate a key. Keys start with `imp_`.
3. **Call `/infer`** - Send your input features as JSON. The API routes the request to your deployed model container and returns the prediction.

```
Dashboard  ──train──►  Deployed model container
                               ▲
Your app  ──POST /infer──►  Inference API  ──proxy──►  container
```

## Plans & access

API keys are available on all plans. Se rate limiting below.

| Plan       | Requests / minute |
| ---------- | :---------------: |
| Pro        |        120        |
| Team       |        300        |
| Enterprise |       1 000       |

Upgrade at [app.impulselabs.ai/billing](https://app.impulselabs.ai/billing).


# Quickstart
Source: https://docs.impulselabs.ai/quickstart

Train a model in the dashboard and get your first inference in under 5 minutes

## Step 1 — Train a model

1. Go to [app.impulselabs.ai](https://app.impulselabs.ai) and sign in.
2. Upload a CSV dataset under **Datasets**.
3. Click **Train Model**, pick your target column, and start training.
4. Once training finishes, note the **Deployment ID** shown on the model card — you'll need it when calling `/infer`.

<Note>
  Deployment IDs look like `clf-titanic-survived` or a UUID. You can find them on the **Models** page in the dashboard.
</Note>

## Step 2 — Create an API key

1. In the dashboard, go to **Settings → API Keys**.
2. Click **New API Key**, give it a name (e.g. `my-app`), and click **Create**.
3. Copy the key immediately — it starts with `imp_` and is shown **only once**.

<Warning>
  Store your API key securely (e.g. in an environment variable). It cannot be retrieved after creation.
</Warning>

```bash theme={null}
export IMPULSE_API_KEY="imp_your_key_here"
export DEPLOYMENT_ID="your-deployment-id"
```

## Step 3 — Check deployment status

Before calling `/infer`, confirm the model is `ACTIVE`:

```bash theme={null}
curl -s "https://inference.impulselabs.ai/deploy/status?deployment_id=$DEPLOYMENT_ID" \
  -H "Authorization: Bearer $IMPULSE_API_KEY" | jq .status
```

Expected response:

```json theme={null}
{
  "deployment_id": "your-deployment-id",
  "status": "ACTIVE"
}
```

<Tip>
  If status is `CREATED` or `BUILDING`, wait a few seconds and retry — the model container is warming up.
</Tip>

## Step 4 — Run your first inference

Replace the `inputs` fields with your actual feature column names and values:

```bash theme={null}
curl -s -X POST "https://inference.impulselabs.ai/infer" \
  -H "Authorization: Bearer $IMPULSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_id": "'$DEPLOYMENT_ID'",
    "inputs": {
      "Pclass": 3,
      "Sex": "male",
      "Age": 22,
      "SibSp": 1,
      "Parch": 0,
      "Fare": 7.25,
      "Embarked": "S"
    }
  }'
```

Response:

```json theme={null}
{
  "prediction": 0,
  "probability": 0.142,
  "target": "Survived"
}
```

## Next steps

<CardGroup>
  <Card title="Use with Codex" icon="terminal" href="/codex">
    Train, inspect, and deploy models from Codex
  </Card>

  <Card title="Use with Claude" icon="terminal" href="/claude">
    Train, inspect, and deploy models from Claude Desktop or Claude Code
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Manage multiple API keys
  </Card>

  <Card title="Rate limits" icon="gauge" href="/api-reference/rate-limits">
    Understand limits and headers
  </Card>

  <Card title="Error reference" icon="circle-exclamation" href="/api-reference/errors">
    Handle errors gracefully
  </Card>

  <Card title="Inference API" icon="bolt" href="/api-reference/inference/run">
    Full parameter reference
  </Card>
</CardGroup>