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

# Introduction

> Overview of the SquadVault Public API for scripts, bots, and external tools.

The Public API lets you read and write SquadVault data for an organization using API keys. Use it for scripts, bots, Discord tooling, and internal integrations.

## Base URL

```bash theme={null}
https://api.squadvault.xyz/v1
```

All Public API endpoints live under `/v1`. Organization API keys only work on this versioned path. App proxy paths without `/v1` are for the SquadVault dashboard (session auth) and are not the integration contract.

Production integrations should always use `https://api.squadvault.xyz/v1`.

## What you can do

| Area                | Operations                                        |
| ------------------- | ------------------------------------------------- |
| Teams               | List, get, create, update, delete                 |
| Players             | List, get, create, update, delete                 |
| Documents           | List, download URL, create, update, delete        |
| Tryout applications | List, get, update status/notes, convert to player |
| Uploads             | Request a presigned URL for document files        |

Calendar, tasks, availability, and Discord management are not part of this Public API surface yet.

## Organization ID

The API key is scoped to one organization, but most operations still require that organization's ID. It must match the key. Missing or mismatched IDs return `400 invalidRequest` or `403 forbidden`.

| Where     | Endpoints                                                                                                                                                                                     |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Path      | `GET /teams/{organizationId}`, `GET /teams/{organizationId}/{teamId}`, `GET /players/{organizationId}`, `GET /players/{organizationId}/{playerId}`, `GET /documents/{organizationId}`         |
| Query     | `GET /tryout-applications`, `GET /tryout-applications/{applicationId}`                                                                                                                        |
| JSON body | `POST /teams`, `POST /players`, `POST /documents`, `POST /uploads/document-file`, `PATCH /tryout-applications/{applicationId}`, `POST /tryout-applications/{applicationId}/convert-to-player` |

Team, player, and document **update/delete/download** resolve the organization from the resource ID. Tryout **get**, **update**, and **convert** do not — always send `organizationId`.

## Prerequisites

1. An organization on a plan that includes API access.
2. An organization API key from **Integrations → API keys**.
3. Permissions on the key that match the endpoints you call.

## Quick example

```bash theme={null}
curl -X GET "https://api.squadvault.xyz/v1/teams/YOUR_ORG_ID" \
  -H "x-api-key: sv_org_your_api_key"
```

## Next

<Columns cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Send organization API keys with every request.
  </Card>

  <Card title="Permissions" icon="shield" href="/api/permissions">
    Match key permissions to each endpoint.
  </Card>
</Columns>