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

# Quickstart

> Authenticate and make your first Ekso API call — list boards, create an item, and handle errors.

This guide walks you through authenticating with the Ekso API and making your first requests. For details on API architecture, error formats, and response conventions, see the [API overview](/guide/api/overview).

## Base URL

All API requests target your install's URL — the `PublicUrl` you set during the `/startup` wizard:

```text theme={null}
https://ekso.acme.com/api/
```

Replace `ekso.acme.com` with your install's hostname.

## Authentication

Ekso uses **OAuth 2.0 with PKCE**. The flow works like this:

<Steps>
  <Step title="Discover endpoints">
    Fetch the OAuth metadata from your install:

    ```bash theme={null}
    curl https://ekso.acme.com/.well-known/oauth-authorization-server
    ```

    This returns the authorization, token, and registration endpoints.
  </Step>

  <Step title="Authorize and get a token">
    Direct the user to the authorization endpoint with a PKCE code challenge. After the user approves, exchange the authorization code for an access token at the token endpoint.

    See the full [OAuth 2.0 details](/api-reference/introduction#oauth-20) in the API reference.
  </Step>

  <Step title="Include the token in requests">
    Add the token to every API request:

    ```bash theme={null}
    curl https://ekso.acme.com/api/board \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```
  </Step>
</Steps>

## List your boards

Once authenticated, list the boards visible to your account:

```bash theme={null}
curl https://ekso.acme.com/api/board \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json Response theme={null}
[
  {
    "entity": "b1a2c3d4-...",
    "name": "Q1 Sprint Board",
    "description": "Main delivery board for Q1",
    "budgetHours": 400,
    "locked": false,
    "archived": false
  }
]
```

## Create an item

Items are the core unit of work in Ekso. Each item belongs to a container and follows a process that defines its workflow.

To create an item, you need a `containerId` and a `processId`. List your containers first:

```bash theme={null}
curl https://ekso.acme.com/api/container \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

Then create the item:

```bash theme={null}
curl -X POST https://ekso.acme.com/api/item \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "containerId": "CONTAINER_ID",
    "processId": "PROCESS_ID",
    "field": [
      { "fieldId": "Name", "value": "Fix login timeout" }
    ]
  }'
```

The response includes the item's key (e.g., `GEM-123`), status, and all field values.

<Tip>
  Items carry a dynamic set of fields controlled by their process and container permissions. To understand the full field model, discover available field types, and use the screen endpoint for permission-aware field discovery, see [Items and fields](/guide/api/items-and-fields).
</Tip>

## Error handling

If something goes wrong, the API returns a JSON error with a `kind`, `message`, and optional `fields` array:

```json theme={null}
{
  "kind": "Validation",
  "message": "Human-readable error description",
  "fields": [
    { "field": "containerId", "code": "required" }
  ]
}
```

Common status codes: `400` (validation), `403` (permission), `422` (business logic), `500` (server error). See the [API overview](/guide/api/overview#error-format) for the full error reference.

## Next steps

<Columns cols={3}>
  <Card title="API overview" icon="book" href="/guide/api/overview">
    Authentication details, error format, and response conventions.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Full REST API with all endpoints and schemas.
  </Card>

  <Card title="MCP tools" icon="robot" href="/mcp-tools/introduction">
    Connect AI agents directly to Ekso — no REST calls needed.
  </Card>
</Columns>