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

# Your First API Call

> Make a real API call and understand the response format.

# Your First API Call

This guide walks through making a real API call and understanding the response.

## Example: List HubSpot Contacts

```bash theme={null}
curl -X POST https://ascend-gateway-v5.ascendgtm.workers.dev/api/v1/ascend/hubspot \
  -H "Authorization: Bearer $ASCEND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "list",
    "object_type": "contacts",
    "limit": 2,
    "properties": ["email", "firstname", "lastname"]
  }'
```

### Full response

```json theme={null}
{
  "success": true,
  "status": 200,
  "data": {
    "results": [
      {
        "id": "123",
        "properties": {
          "email": "alice@example.com",
          "firstname": "Alice",
          "lastname": "Smith"
        }
      }
    ],
    "paging": {"next": {"after": "124"}}
  }
}
```

### Compact response (saves tokens)

Add `"format": "compact"` to strip the wrapper:

```json theme={null}
{
  "results": [{"id": "123", "properties": {"email": "alice@example.com", ...}}],
  "paging": {"next": {"after": "124"}}
}
```

### Field-picked response (saves more tokens)

Add `"fields": ["id", "properties.email"]`:

```json theme={null}
{
  "results": [{"id": "123", "properties": {"email": "alice@example.com"}}],
  "paging": {"next": {"after": "124"}}
}
```

## Understanding Errors

All errors follow this structure:

```json theme={null}
{
  "error": "Human-readable message",
  "code": "ERROR_CODE",
  "status": 401
}
```

| Code               | Meaning                                           |
| ------------------ | ------------------------------------------------- |
| `AUTH_FAILED`      | Invalid or missing bearer token                   |
| `TENANT_NOT_FOUND` | Token valid but tenant config missing             |
| `TOKEN_MISSING`    | No API token stored for this provider             |
| `TOKEN_EXPIRED`    | OAuth token expired (auto-refreshes within 10min) |
| `UPSTREAM_ERROR`   | The target API returned an error                  |
| `VALIDATION_ERROR` | Invalid request parameters                        |
| `RATE_LIMITED`     | Too many requests                                 |