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

# API overview

> Base URL, resource model, and how to call the Gapstack API.

The Gapstack API is a REST API for tenants, projects, environments, resources, AWS accounts, and marketplace integrations.

Use the [interactive playground](https://9nr7sbhimh.execute-api.us-west-1.amazonaws.com/prod/swagger/) on each endpoint page, or send requests to the production base URL.

<Card title="OpenAPI specification" icon="file-code" href="https://9nr7sbhimh.execute-api.us-west-1.amazonaws.com/prod/swagger/">
  Browse the live Swagger UI and download `openapi.yaml`.
</Card>

## Base URL

```bash theme={null}
https://9nr7sbhimh.execute-api.us-west-1.amazonaws.com/prod
```

All paths in this reference are relative to that URL. For example, `GET /healthcheck` is:

```bash theme={null}
curl https://9nr7sbhimh.execute-api.us-west-1.amazonaws.com/prod/healthcheck
```

## Authenticate

Most endpoints accept either a Cognito JWT or a tenant API key. See [Authentication](/api-reference/authentication).

<CodeGroup>
  ```bash JWT theme={null}
  curl https://9nr7sbhimh.execute-api.us-west-1.amazonaws.com/prod/tenant \
    -H "Authorization: Bearer YOUR_JWT"
  ```

  ```bash API key theme={null}
  curl https://9nr7sbhimh.execute-api.us-west-1.amazonaws.com/prod/project \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Tenant-Id: YOUR_TENANT_ID"
  ```
</CodeGroup>

## Tenant context

Project, environment, resource, and related endpoints require a `Tenant-Id` header. Tenant and invitation endpoints take the tenant in the path instead, such as `/tenant/{tenantId}`.

```bash theme={null}
curl https://9nr7sbhimh.execute-api.us-west-1.amazonaws.com/prod/project \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Tenant-Id: YOUR_TENANT_ID"
```

## Resource model

Gapstack resources nest in this order:

<Steps>
  <Step title="Tenant">
    The organization. Create one with `POST /tenant`, then create API keys and invite members.
  </Step>

  <Step title="Project">
    A grouping inside a tenant. Projects organize environments. Creating a project does not create a CloudFormation stack.
  </Step>

  <Step title="Environment">
    A deployable instance under a project. Each environment has its own CloudFormation stack, plus variables, artifacts, and deploy actions.
  </Step>

  <Step title="Resource">
    A cloud resource attached to an environment, such as a Lambda function.
  </Step>
</Steps>

Linked AWS accounts, marketplace integrations, workflows, and cost data hang off this same tenant context.

## Pagination

List endpoints that accept `limit` and `cursor` return a page of results plus a cursor for the next page. Pass the cursor back on the following request until the response has no cursor.