# [Product name] API: Overview and Getting Started

> Landing page for an API: what it does, how to authenticate, how to make
> the first request, the main resources, errors and limits. Based on
> common industry practice for API documentation. Replace every
> `[bracketed]` value and every row marked *Example*.

<!--
Guidance: How to use this template
- This page answers "Is this API for me, and how do I make one call?". Keep
  endpoint details in the API reference and deep topics in the developer guide.
- A developer should reach a successful response within five minutes of
  opening the page. Test the steps with a brand-new account.
- Use one realistic resource throughout the page so examples build on
  each other.
- Keep the page short enough to read in one sitting; link out for detail.
-->

| Field | Value |
|---|---|
| API version | [v2] |
| Status | [Beta / Generally available / Deprecated] |
| Owner | [@api-team] |
| Last updated | YYYY-MM-DD |
| OpenAPI description | [https://api.example.com/v2/openapi.json] |

## What the API does

<!-- Guidance: Two or three sentences on the jobs a developer can automate, then concrete use cases. Say plainly what is out of scope. -->

The [Product name] API lets your software [manage projects, tasks and
comments] in a [Product name] workspace. It is a REST API over HTTPS that
accepts and returns JSON, uses standard HTTP methods and status codes,
and is described by an OpenAPI document you can import into tools such
as Postman or code generators.

Common uses:

- *Example:* Create tasks automatically from support tickets.
- *Example:* Sync task status to a data warehouse every night.
- *Example:* Post a comment when a build fails in CI.

Not available through the API: [billing changes, workspace deletion].

## Before you start

<!-- Guidance: List everything needed before step one so readers do not stop half-way. -->

You need:

- A [Product name] account with the **Member** role or higher in at least
  one workspace. Sandbox accounts are free at [https://example.com/dev].
- A command-line HTTP client such as `curl` 7.68 or later, or an API tool
  such as Postman or Bruno.
- About five minutes.

## Base URL and environments

<!-- Guidance: Give every base URL a developer may need and say how they differ. -->

| Environment | Base URL | Purpose |
|---|---|---|
| Production | `https://api.example.com/v2` | Real workspaces and data |
| Sandbox | `https://sandbox.api.example.com/v2` | Testing with disposable data |

All requests must use HTTPS with TLS 1.2 or later. Requests over plain
HTTP are rejected, not redirected.

The version is part of the path (`/v2`). Additive changes, such as new
fields or new endpoints, can appear at any time without a version change,
so write clients that ignore unknown fields. Breaking changes only ship
in a new major version, announced at least [12 months] before the old one
is retired in the [changelog].

## Authenticate in three steps

<!-- Guidance: The shortest safe path to a working credential. Mention the safer alternative (OAuth, restricted tokens) for production. -->

1. **Create a token.** In [Product name], go to **Settings > Developer >
   Personal access tokens**, select **New token**, choose the scopes
   `tasks:read` and `tasks:write`, and copy the token. It is shown once.
2. **Store it safely.** Put it in an environment variable or secret
   manager, never in source control:

   ```bash
   export EXAMPLE_TOKEN="pat_[...]"
   ```

3. **Send it with every request** in the `Authorization` header:

   ```http
   Authorization: Bearer pat_[...]
   ```

Personal access tokens act as you. For apps used by other people, use
OAuth 2.0 with PKCE as described in the [developer guide].

## Make your first request

<!-- Guidance: One read request that returns real data, then one write request. Show the full response so readers can compare. -->

List the projects you can see:

```bash
curl https://api.example.com/v2/projects \
  -H "Authorization: Bearer $EXAMPLE_TOKEN"
```

Expected response (status `200 OK`):

```json
{
  "data": [
    { "id": "prj_01H8X", "name": "Website relaunch", "created_at": "2026-09-14T08:12:00Z" }
  ],
  "has_more": false
}
```

Now create a task in that project:

```bash
curl https://api.example.com/v2/tasks \
  -H "Authorization: Bearer $EXAMPLE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"project_id":"prj_01H8X","title":"Review homepage copy","due_on":"2026-11-03"}'
```

The response has status `201 Created` and contains the new task with its
`id`. Open the project in [Product name] and you will see the task.

The `Idempotency-Key` header makes the request safe to retry: if your
connection drops before you see the response, send the same request with
the same key and the API returns the original task instead of creating a
second one. Keys are remembered for [24 hours]. Use a new key for every
new task you intend to create.

If you get `401`, the token is missing or mistyped; if you get `403`, it
lacks the `tasks:write` scope. See [Errors](#errors) for the full list.

## Key resources

<!-- Guidance: List the main resources with one line each and a link to their reference page. Keep the order the reader will meet them in. -->

| Resource | Path | What it represents | Main operations |
|---|---|---|---|
| Project | `/projects` | A container for tasks with its own members | List, get, create, update, archive |
| Task | `/tasks` | A unit of work with assignee, status and due date | List, get, create, update, delete |
| Comment | `/tasks/{id}/comments` | A message on a task | List, create, delete |
| User | `/users` | A member of the workspace | List, get |
| Webhook | `/webhooks` | A subscription to events | List, create, delete |

Conventions that apply to all resources:

- IDs are opaque strings with a type prefix, for example `tsk_`.
- Timestamps are ISO 8601 in UTC; dates without time use `YYYY-MM-DD`.
- List endpoints use cursor pagination with `limit` (maximum 100) and
  `starting_after`.

## Errors

<!-- Guidance: Show the error format and the handful of codes every client must handle. Link to the full list. -->

Errors return a non-2xx status and a body like this:

```json
{ "error": { "code": "validation_failed", "message": "due_on must be a date", "field": "due_on", "request_id": "req_7Hk2" } }
```

| Status | Code | What to do |
|---|---|---|
| 400 | `validation_failed` | Fix the field named in `field` |
| 401 | `unauthenticated` | Check the token and its expiry |
| 403 | `insufficient_scope` | Create a token with the needed scope |
| 404 | `not_found` | Check the ID and that you can access it |
| 429 | `rate_limited` | Wait `Retry-After` seconds, then retry |
| 5xx | `server_error` | Retry with exponential backoff; contact support with `request_id` if it persists |

## Limits

<!-- Guidance: List every limit a normal integration can hit, with the number. Unknown limits cause production surprises. -->

| Limit | Value | How you know |
|---|---|---|
| Requests per minute per token | [600] | `RateLimit-Remaining` header |
| Request body size | [1 MB] | `413` response |
| Items per page | [100] | `limit` above 100 is rejected |
| Webhooks per workspace | [20] | `422` on create |
| Attachment size | [25 MB] | `413` response |

Spread bulk jobs over time instead of sending bursts, and prefer
webhooks over polling: one webhook subscription replaces thousands of
list requests per day. Need more? Contact [api-support@example.com] with your use case.

## Next steps

<!-- Guidance: Point to the three or four pages most readers need next, in a sensible order. -->

- [Developer guide]: authentication with OAuth, pagination, webhooks, testing.
- [API reference]: every endpoint, parameter and field.
- [SDKs]: official libraries for [Python and JavaScript].
- [Changelog] and [status page]: stay informed about changes and incidents.

## Getting help

<!-- Guidance: Say where to ask questions, where to report production problems, and what information to include. -->

For questions, use [the developer forum]. For problems with production
traffic, email [api-support@example.com] with the `request_id`, the
endpoint and the time of the request. Never include your token.

## Standard and licence note

Based on common industry practice for API overview and getting-started
pages. Template licence: MIT.