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

# Welcome to Overshoot

Overshoot enables developers to build realtime vision applications in two steps:

* Create a `/streams` session and connect a live video source to it
* Ask any model about any moment of the video stream via `/chat/completions` request

That's it. 2 HTTP stateless endpoints is all you need to build anything.

If you can't be bothered to read the documentation, here's what you need to know:

1. When you create a [Stream](/the-stream) , you get back a `Stream ID`, a LiveKit Room URL with a token. Use a LiveKit SDK to publish your video stream in the room.
2. Once a [Stream](/the-stream) is connected, you can refer to parts or all of it inside your OpenAI Compatible [Chat Completion](/chat-completion) request.
   * To refer to single frames, pass them as `image_url` inside the [message content](https://developers.openai.com/api/reference/resources/chat#\(resource\)%20chat.completions%20%3E%20\(model\)%20chat_completion_content_part%20%3E%20\(schema\)).
   ```json theme={null}
   // last frame
   {
     "type": "image_url",
     "image_url": {
       "url": "ovs://streams/{stream_id}?frame_index=-1"
     }
   }
   ```
   * Similarly, to refer to segments in the live stream, pass them as `video_url`
   ```json theme={null}
   // last 5 seconds
   {
     "type": "video_url",
     "video_url": {
       "url": "ovs://streams/{stream_id}?start_offset_ms=-5000"
     }
   }
   ```

Hope this makes sense.

Enjoy!

<CardGroup cols={2}>
  <Card title="Quickstart" icon="play" href="/quickstart">
    Webcam to model in four steps.
  </Card>

  <Card title="The Stream" icon="video" href="/the-stream">
    Lifecycle, leases, and how to keep a session alive.
  </Card>

  <Card title="Chat Completion" icon="message" href="/chat-completion">
    URL grammar for referencing frames and segments.
  </Card>

  <Card title="Models" icon="microchip-ai" href="/models">
    What's available, context limits, picking the right one.
  </Card>
</CardGroup>

## Mental model for agents

See the [Glossary](/glossary) for canonical definitions of every term used across the docs.

A `Stream` is a leased server-side handle for a live video feed. Once a publisher is attached (via the LiveKit room URL + token returned at creation), Overshoot ingests frames continuously and indexes them. The handle is opaque from the model's perspective — you reference moments inside the stream by URL, not by uploading bytes.

A chat completion request is OpenAI-compatible. The only Overshoot-specific construct is the URI inside `image_url` / `video_url` content parts:

```
ovs://streams/{stream_id}?<anchor>
```

The `ovs://` scheme is a reference identifier — the server parses `stream_id` and the query out of it and resolves frames internally. It is not a fetchable URL.

Where `<anchor>` is exactly one of:

* `frame_index=N` — Nth frame of the stream's lifetime. Negative = from live edge. `frame_index=-1` is "the latest frame".
* `timestamp_ms=N` — absolute stream-clock timestamp in ms.
* `offset_ms=N` — offset from now, in ms. Negative = past.

Video segments take a `start_*` anchor and an optional `end_*` anchor (defaults to live edge). Use the same field names with a `start_` / `end_` prefix.

## Authentication

All endpoints except `GET /models` require a bearer token: `Authorization: Bearer ovs-...`. Keys are issued from the [dashboard](https://platform.overshoot.ai).

## Lifecycle invariants

* A stream is deleted \~5 minutes after the last keepalive or after `DELETE /streams/{id}`.
* A stream's `state` transitions only forward: `active` → `ended`. There is no resume.
* A new keepalive returns a fresh LiveKit token; the old token may stop working when the publisher reconnects.
* `frame_index` is monotonically increasing across the stream's lifetime, even after eviction. Old indices outside the retention window resolve to the oldest available frame (intersection-with-availability semantics).

## Endpoint surface

| Method   | Path                             | Auth | Purpose                                      |
| -------- | -------------------------------- | ---- | -------------------------------------------- |
| `POST`   | `/v1beta/chat/completions`       | Yes  | OpenAI-compatible chat completions.          |
| `POST`   | `/v1beta/streams`                | Yes  | Create a stream, get a LiveKit room + token. |
| `GET`    | `/v1beta/streams/{id}`           | Yes  | Inspect stream state.                        |
| `POST`   | `/v1beta/streams/{id}/keepalive` | Yes  | Renew lease, get a fresh token.              |
| `DELETE` | `/v1beta/streams/{id}`           | Yes  | End the stream.                              |
| `GET`    | `/v1beta/models`                 | No   | List available vision-language models.       |
| `GET`    | `/billing/pricing`               | No   | List public model prices.                    |
| `GET`    | `/billing/pricing/{model}`       | No   | Pricing for one model.                       |
| `GET`    | `/billing/accounts/me/balance`   | Yes  | Get prepaid balance.                         |
| `POST`   | `/billing/checkout`              | Yes  | Buy prepaid credits.                         |