[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.

What the API does

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

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

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

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:

   export EXAMPLE_TOKEN="pat_[...]"
   

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

   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

List the projects you can see:

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

Expected response (status 200 OK):

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

Now create a task in that project:

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 for the full list.

Key resources

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

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

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

Limits

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 [[email protected]] with your use case.

Next steps

• [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

For questions, use [the developer forum]. For problems with production traffic, email [[email protected]] 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.