# API reference

The public v1 contract for downloads, jobs, files, and playlists.

## Base URL and version

```text
https://api.mediafilez.online/api/v1
```

The `/v1` path is the HTTP contract version. A service release such as `v0.2.2` is a software version, not a different base path.

Examples use illustrative IDs and shortened response objects. Replace them with the IDs returned by your own requests. The hosted service may apply lower limits than a self-hosted configuration.

In a route such as `/jobs/:id`, `:id` is a placeholder. Replace it with the returned job ID and omit the colon. A playlist's `:itemId` is the ID of a saved link, not a downloaded file. You do not need to decode an ID to use it.

## Authentication and bodies

Use an API key from your backend:

```http
Authorization: ApiKey YOUR_API_KEY
Content-Type: application/json
```

`Content-Type` is needed when you send JSON. A bodyless `GET`, `DELETE`, or cancellation request does not need it. See [authentication](/docs/en/reference/authentication) for browser sessions and key management restrictions.

## Endpoint map

| Resource  | Main routes                                                      | Authentication                                                            |
| --------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Account   | `GET /users/me`                                                  | Key or user session                                                       |
| Media     | `POST /media/resolve`, `POST /media/download`                    | Key/session for partner downloads; anonymous access depends on deployment |
| Jobs      | `GET /jobs/:id`, `POST /jobs/:id/cancel`, `GET /jobs/:id/events` | Owning account; anonymous jobs are IP-scoped when enabled                 |
| Files     | `GET /files/:id`                                                 | Owning account for private results                                        |
| Batches   | `POST /batches`, `GET /batches/:id`                              | Owning account                                                            |
| Playlists | `/playlists` and `/playlists/:id/items`                          | Owner for writes; sharing controls reads                                  |
| Health    | `GET /health`, `GET /health/ready`                               | None                                                                      |

For community listings or partnership enquiries, see [partners and communities](/docs/en/servers-api).

## Status and errors

`200` returns data, `201` creates a playlist, `202` accepts background work, and `204` has no response body. Parse JSON only when a body exists.

```json
{
    "error": {
        "code": "JOB_NOT_FOUND",
        "message": "Job not found.",
        "requestId": "req_example"
    }
}
```

See [errors](/docs/en/reference/errors) and [rate limits](/docs/en/reference/limits).