# REST quickstart

**For IT and engineering teams.** This is the organization-level integration surface — authenticated with a key issued to your company rather than to any individual. If you're an end user who wants to work with your own calls from an AI assistant, you want the [MCP connector](/mcp-connector) instead; it needs no code.

The Junior REST API returns call (interview) records and their transcripts, and can create projects where that's enabled for your organization.

Base URL:

```
https://api.junior.ai/v1
```

## Authentication

Every request needs an API key, issued to your organization by the Junior team and sent as a bearer token:

```bash
curl https://api.junior.ai/v1/calls \
  -H "Authorization: Bearer jr_live_..."
```

Keys are shown once at issuance — store them in your secret manager. A missing or invalid key returns `401` with code `unauthorized`.

## Your first request

List calls from a date range. **`start_date` and `end_date` are both required** — the endpoint returns `400` without them. Each is an RFC 3339 date-time; UTC (`...Z`) or a numeric offset (`...-05:00`) are both accepted:

```bash
curl -G "https://api.junior.ai/v1/calls" \
  --data-urlencode "start_date=2026-01-01T00:00:00Z" \
  --data-urlencode "end_date=2026-12-31T23:59:59Z" \
  --data-urlencode "per_page=25" \
  -H "Authorization: Bearer $JUNIOR_API_KEY"
```

Then fetch one call in full, using a `call_id` from that response:

```bash
curl "https://api.junior.ai/v1/calls/$CALL_ID" \
  -H "Authorization: Bearer $JUNIOR_API_KEY"
```

## Pagination

List endpoints are page-based. Pass `page` (1-indexed) and `per_page`, and read the `pagination` object to decide whether to keep going:

```json
{
  "data": [{ "call_id": "..." }],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_items": 412,
    "total_pages": 17
  }
}
```

Keep requesting until `page` equals `total_pages`. List responses return call references — fetch `/calls/{call_id}` for the full record including the transcript.

## Errors

Every error uses the same envelope:

```json
{
  "error": {
    "code": "bad_request",
    "message": "Human-readable explanation",
    "request_id": "01HQ..."
  }
}
```

`code` is one of `bad_request`, `unauthorized`, `not_found`, `rate_limited`, or `internal_error`. **Log `request_id`** — it's the fastest way for Junior support to trace a specific failed call.

## Rate limits

Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. On `429` (`rate_limited`), back off until the reset timestamp rather than retrying immediately.

## Field availability

Some fields on a call are gated by your organization's configuration — for example, participant emails are present only when your organization has enabled that field. When a field isn't enabled, it's omitted or `null` rather than causing an error, so treat these as optional in your client.

## Full reference

See the [API reference](/openapi) for every endpoint, parameter, and response field.