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

# Quickstart

> Make your first authenticated Alterscope API call in about five minutes.

This walks you from an API key to a parsed response in three steps. You'll need a terminal and either `curl`, Python, or Node.

## 1. Get an API key

Create a key in the [Developer Portal](https://app.alterscope.org/connections) under your organization's API Keys settings. A Free-tier key works for this guide. Keys are prefixed `sk_live_`.

<Warning>
  Store the key in an environment variable, never in source control. Rotate it immediately if it leaks.
</Warning>

```bash theme={null}
export ALTERSCOPE_API_KEY="sk_live_..."
```

## 2. Make your first request

<Snippet file="base-url.mdx" />

<Snippet file="auth-header.mdx" />

This fetches one yield opportunity so you can see the envelope shape:

<CodeGroup>
  ```bash curl theme={null}
  curl -sS -H "Authorization: Bearer $ALTERSCOPE_API_KEY" \
    "https://api.alterscope.org/v2/yield/opportunities?limit=1"
  ```

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

  resp = requests.get(
      "https://api.alterscope.org/v2/yield/opportunities",
      params={"limit": 1},
      headers={"Authorization": f"Bearer {os.environ['ALTERSCOPE_API_KEY']}"},
      timeout=20,
  )
  resp.raise_for_status()
  body = resp.json()
  print(body["meta"]["_agentic"]["freshness"]["status"])
  ```

  ```typescript TypeScript theme={null}
  const resp = await fetch(
    "https://api.alterscope.org/v2/yield/opportunities?limit=1",
    { headers: { Authorization: `Bearer ${process.env.ALTERSCOPE_API_KEY}` } },
  );
  if (!resp.ok) throw new Error(`Alterscope API returned ${resp.status}`);
  const body = await resp.json();
  console.log(body.meta._agentic.freshness.status);
  ```
</CodeGroup>

## 3. Read the response

A successful call returns `200` and a JSON envelope. The result is under `data`; the freshness and quality signal is under `meta._agentic`:

```json theme={null}
{
  "data": [ { "...": "one yield opportunity" } ],
  "meta": {
    "request_id": "req_…",
    "_agentic": {
      "freshness": { "status": "fresh" },
      "quality_gate": { "verdict": "pass" }
    }
  }
}
```

**You're done when:** the call returns `200`, `data` contains one opportunity, and `meta._agentic.freshness.status` prints. If you got a `401` or `403`, check [Authentication](/develop/get-started/authentication) and [Scopes](/develop/get-started/scopes); for `429`, see [Rate limits](/develop/get-started/rate-limits); for any other status, see [Errors](/develop/get-started/errors).

## Next steps

<CardGroup cols={2}>
  <Card title="SDKs" icon="cube" href="/develop/sdks/overview">
    TypeScript, Python, and Go clients.
  </Card>

  <Card title="Response envelope" icon="layer-group" href="/develop/concepts/response-envelope">
    The full `data` + `meta` contract.
  </Card>

  <Card title="Guides" icon="book-open" href="/recipes/detect-depeg-realtime">
    Worked recipes for common workflows.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/overview">
    Every endpoint and parameter.
  </Card>
</CardGroup>