Your First API Call

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

Example: List HubSpot Contacts

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

{
  "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:

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

Field-picked response (saves more tokens)

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

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

Understanding Errors

All errors follow this structure:

{
  "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