Skip to content

GobbleCube Enterprise API FINAL (1.0.0)

Overview

Enterprise-ready API for campaign and job management on GobbleCube platform.

Getting Started

Authentication

All requests must include:

  • X-API-Key: Your API key (90-day expiry, managed through dashboard)
  • Platform: Platform name (zepto)

API Key Management:

  • API keys expire after 90 days
  • Key generation and rotation managed through GobbleCube dashboard
  • IP whitelisting supported for enhanced security
  • Environment segregation at account level (production vs sandbox accounts)

Request Headers

Required Headers:

  • X-API-Key: Your API key for authentication
  • Platform: Platform name (zepto)

Optional Headers:

  • X-Request-ID: Request ID for traceability (if not provided, one will be generated)

Response Headers:

  • X-Request-ID: Request ID for traceability and audit logging (always present)

Features

  • Campaign Management: Bulk creation, list, update, get details
  • Keyword Management: Add, update, remove, bulk operations
  • Product & City Management: Add/remove products, create groups
  • Live Data: Keyword Share of Search (SOS) with real-time scraping
  • T-1 Data: Detailed campaign performance metrics (yesterday's data)
  • Job Management: Poll async job status, bulk job creation

Postman Collection

Please contact your POC (Point of Contact) to get access to the Postman collection for faster integration and testing.

API Reference

Rate Limiting

Rate Limits:

  • Overall API: 200 requests per minute (RPM)
  • Sliding Window: Rate limiting implemented using sliding window algorithm
  • Per Application: Rate limits applied per API key/application
  • Keyword SOS: 5 keywords every 15 minutes (per API key)
  • Page Limit: Maximum page limit for all paginated GET APIs is 200 per page

Rate Limit Headers: When rate limits are approached or exceeded, the following headers are included in responses:

  • X-RateLimit-Limit: Maximum requests allowed per window
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Time when the rate limit window resets

Rate Limit Exceeded:

  • HTTP Status: 429 Too Many Requests
  • Response includes retry-after information
  • Implement exponential backoff for retries

Error Handling

Standard HTTP Status Codes:

  • 200 OK - Successful request
  • 201 Created - Resource created successfully
  • 202 Accepted - Request accepted for async processing
  • 400 Bad Request - Invalid request parameters or payload
  • 401 Unauthorized - Missing or invalid API key
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error
  • 502 Bad Gateway - Gateway error
  • 503 Service Unavailable - Service temporarily unavailable

Error Response Format:

{
  "code": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": "Additional error details (optional)"
}

Retry Logic:

  • Safe to retry API calls with exponential backoff up to 3 times
  • Use X-Request-ID from response to track retries
  • Do not retry on 4xx errors (except 429 with retry-after)
  • Retry on 5xx errors and network failures

Idempotency

  • All operations support idempotency
  • Duplicate request detection mechanism in place
  • Use X-Request-ID header to ensure idempotency across retries
  • Same request with same X-Request-ID will return same result

Request Ordering

  • Requests are queued and processed based on workflow type priority
  • For deterministic ordering requirements, contact support for guidance
  • Campaign-level ordering can be configured if needed

Data Freshness & Sync

Platform Sync:

  • Two-way sync between GobbleCube and platform ad consoles
  • Platform to GobbleCube sync: Maximum SLA of 3 hours
  • Data accuracy maintained through continuous synchronization

T-1 Data:

  • T-1 data represents yesterday's performance metrics
  • Available through GET /v1/t1-data endpoint
  • Data is refreshed daily

Historical Data:

  • Historical SOS snapshots available
  • Live data available through API endpoints

Audit & Logging

Request Tracking:

  • All requests return X-Request-ID in response headers
  • Request ID used for logging and audit trail
  • Include X-Request-ID in support requests for faster resolution

Audit Trail:

  • All API requests logged with: request ID, entity ID, timestamp, payload, response code
  • Log retention: 90 days
  • Audit trails available through request logs

Daily Summary Logs:

  • Automated daily summary logs will be sent on email
  • Includes all POST and GET activities
  • Contact support for access

API Versioning

Version Policy:

  • Current version: v1
  • Backward compatibility maintained across minor versions
  • Major versions (breaking changes) released as new version endpoints
  • 1 month deprecation notice period for breaking changes
  • Communication via Slack channels for version updates

Versioning Strategy:

  • Standard REST-based versioning
  • Version included in URL path: /v1/...
  • Future versions: /v2/..., etc.

Base URLs

  • Production: https://enterprise-api.gobblecube.ai (Live )

Environment Segregation:

  • Separate accounts for production and sandbox
  • Same API endpoints, different account credentials
  • IP whitelisting supported per environment

Security

Data Encryption:

  • Data encrypted in transit (TLS/HTTPS)
  • Data encrypted at rest
  • HTTP protocol not allowed (HTTPS only)

Data Isolation:

  • Customer data in separate databases
  • Role-based access control (RBAC) ensures Principle of Least Privilege (POLP)
  • Cross-client data access prevented through architecture

Certifications:

  • SOC2 Type II compliance
  • Yearly penetration testing (next report: December 2026)
  • MFA enabled by default (no password-based authentication)

Contact Support: Name: API Support Email: ishant.dahiya@gobblecube.ai

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
https://enterprise-api.gobblecube.ai

v1

Operations

bulk-update

Operations

campaigns

Operations

{campaign_id}

Operations

bid-multipliers

Operations

keywords

Operations

update-bid

Operations

Update keyword bids

Request

Update bids for one or more keywords in a campaign

Security
ApiKeyAuth
Path
campaign_idstringrequired

Campaign ID

Example: string
Headers
x-api-keystring

API key for authentication

Example: string
x-platformstring

Platform identifier

Example: zepto
Bodyapplication/json
keywordsArray of objectsrequired
keywords[].​bidintegerrequired
keywords[].​keywordstringrequired
keywords[].​match_typestringrequired
curl -i -X POST \
  https://enterprise-api.gobblecube.ai/v1/campaigns/string/keywords/update-bid \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-platform: zepto' \
  -d '{
    "keywords": [
      {
        "keyword": "shampoo",
        "match_type": "exact",
        "bid": 150
      }
    ]
  }'

Responses

Successful Response

Bodyapplication/json
successboolean
messagestring
dataobject
Response
application/json
{
  "success": true,
  "message": "Updated 1 of 1 keyword(s) successfully",
  "data": {
    "campaign_id": "2005795",
    "results": [ … ],
    "updated_at": "2026-01-22T12:47:21.542465"
  }
}

products

Operations

cities

Operations

groups

Operations

{product_group_id}

Operations

t1-data

Operations

city-performance

Operations

keyword-performance

Operations

product-performance

Operations