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

# REST API Reference

> Traditional HTTP API for non-MCP consumers.

# REST API Reference

Traditional HTTP API for non-MCP consumers (n8n, Zapier, scripts, mobile apps).

## Base URL

```
https://ascend-gateway-v5.ascendgtm.workers.dev
```

## Authentication

All API endpoints require a Bearer token:

```
Authorization: Bearer YOUR_TOKEN
```

## Endpoints

### POST /api/v1/TENANT/DOMAIN

Proxy a request to any registered API domain.

**Path parameters:**

* `tenant` — Tenant ID (e.g., `ascend`, `kahuna`)
* `domain` — API domain (e.g., `hubspot`, `google_ads`, `slack`)

**Request body:** Domain-specific parameters (same as the MCP tool schema).

**Example:**

```bash theme={null}
curl -X POST /api/v1/ascend/hubspot \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "search", "object_type": "deals", "filters": [{"propertyName": "dealstage", "operator": "EQ", "value": "closedwon"}]}'
```

### GET /health

Health check endpoint (no auth required).

```json theme={null}
{
  "status": "healthy",
  "services": {"kv": "up", "d1": "up"},
  "tokens": {"total": 57, "expiring_soon": 0, "expired": 0},
  "providers": 70
}
```

### POST /mcp

MCP Streamable HTTP endpoint. Used by AI agents (Claude, ChatGPT, Cursor).

Implements the [Model Context Protocol](https://modelcontextprotocol.io/) specification with:

* JSON-RPC 2.0 message format
* Dynamic Client Registration (RFC 7591)
* OAuth 2.1 with PKCE (S256)
* Streamable HTTP transport (spec `2025-11-25`)

## Response Format

All responses follow this structure:

```json theme={null}
{
  "success": true,
  "status": 200,
  "data": { /* upstream API response */ },
  "cache": "MISS"
}
```

Error responses:

```json theme={null}
{
  "error": "Description",
  "code": "ERROR_CODE",
  "status": 401
}
```

## Error Codes

| Code               | HTTP Status | Description               |
| ------------------ | ----------- | ------------------------- |
| `AUTH_FAILED`      | 401         | Invalid or missing token  |
| `TENANT_NOT_FOUND` | 404         | Tenant config not found   |
| `TENANT_SUSPENDED` | 403         | Account suspended         |
| `CONFIG_MISSING`   | 404         | Provider not configured   |
| `TOKEN_MISSING`    | 404         | No API token for provider |
| `TOKEN_EXPIRED`    | 401         | OAuth token expired       |
| `UPSTREAM_ERROR`   | varies      | Target API returned error |
| `VALIDATION_ERROR` | 400         | Invalid parameters        |
| `RATE_LIMITED`     | 429         | Too many requests         |
| `TIMEOUT`          | 504         | 30s timeout exceeded      |