API Reference

API Overview

Learn how to integrate with the Ambient API to automate and extend your brand management workflows.

Last updated: February 17, 2026

The Ambient API enables you to programmatically manage campaigns, content, and analytics. This RESTful API uses JSON for request and response bodies.

Base URL

All API requests should be made to:

https://api.ziviso.africa/v1

Authentication

The Ambient API uses Bearer token authentication. Include your API key in the Authorization header:

curl -X GET "https://api.ziviso.africa/v1/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

Obtaining API Keys

  1. Sign in to your Ambient workspace and navigate to Integrations > API Keys
  2. Click Create API Key
  3. Set the key name and permissions
  4. Copy the key (it won’t be shown again)

Rate Limits

Rate limits are enforced per API key and endpoint policy. The exact limits for your tenant are returned through response headers:

X-RateLimit-Limit: <policy-limit>
X-RateLimit-Remaining: <remaining-requests>
X-RateLimit-Reset: <unix-timestamp>

Use these headers for adaptive client retry behavior and backoff.

Common Endpoints

Campaigns

# List campaigns
GET /v1/campaigns

# Get campaign details
GET /v1/campaigns/{id}

# Create campaign
POST /v1/campaigns

# Update campaign
PUT /v1/campaigns/{id}

# Delete campaign
DELETE /v1/campaigns/{id}

# Deploy campaign
POST /v1/campaigns/{id}/deploy

Content

# Upload content
POST /v1/content/upload

# List content
GET /v1/content

# Get content details
GET /v1/content/{id}

# Delete content
DELETE /v1/content/{id}

Analytics

# Get campaign analytics
GET /v1/analytics/campaigns/{id}

# Get endpoint analytics
GET /v1/analytics/endpoints

# Get engagement metrics
GET /v1/analytics/engagement

Response Format

All responses follow a consistent format:

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 100
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Campaign name is required",
    "details": [
      {
        "field": "name",
        "message": "This field is required"
      }
    ]
  }
}

Webhooks

Subscribe to events for real-time updates:

Available Events

  • campaign.created
  • campaign.deployed
  • campaign.completed
  • content.uploaded
  • endpoint.registered
  • endpoint.offline

Webhook Payload

{
  "event": "campaign.deployed",
  "timestamp": "2024-12-01T10:00:00Z",
  "data": {
    "campaignId": "camp_123",
    "name": "Q4 Holiday Campaign",
    "endpointCount": 500
  }
}

SDKs

Official SDKs are available for:

Need Help?