API Documentation

Complete reference for Glossi's Creative Audit and Analysis API

Overview

The Glossi API enables you to submit advertising creatives for comprehensive analysis, including rendering verification, brand detection, IAB classification, and landing page audits. All endpoints return JSON responses and follow RESTful conventions.

Base URL

https://your-subdomain.glos.si/api

Authentication

The API supports two authentication methods:

1. Session Authentication

Use browser cookies after logging in through the web interface.

2. API Key Authentication

Include your API key in the request header:

Example Request

curl -H "X-API-Key: your_api_key_here" \
  https://glos.si/api/creative/abc123/status

Creative Submission & Polling

These are the core endpoints for submitting creatives and monitoring their processing status.

POST

/api/submitAuth Required

Submit a bid response containing one or more creatives for processing. Each creative will be queued for rendering, analysis, and classification.

Query Parameters

rerunbooleanSet to "true" or "1" to reprocess existing creatives

Request Body

OpenRTB bid response format

Example Request

{
  "id": "bid-123",
  "seatbid": [{
    "seat": "advertiser-seat",
    "bid": [{
      "id": "creative-456",
      "impid": "imp-1",
      "price": 2.5,
      "adm": "<script src='https://example.com/ad.js'></script>",
      "adomain": ["example.com"],
      "crid": "creative-456",
      "w": 300,
      "h": 250
    }]
  }]
}

Success Response

{
  "success": true,
  "message": "Bid response processed successfully",
  "data": {
    "creative_ids": ["creative-456"],
    "submission_id": "sub-789",
    "estimated_completion_time": "2025-10-22T10:30:00.000Z",
    "task_summary": {
      "total_tasks": 5,
      "task_types": [
        "ad_render",
        "adomain_capture",
        "brand_mapping",
        "adomain_analysis",
        "ad_analysis"
      ]
    }
  },
  "meta": {
    "request_id": "req-abc123",
    "submitted_at": "2025-10-22T10:22:00.000Z",
    "processing_queue": "BROWSER_CAPTURE"
  }
}

Processing Time

Estimated processing time is approximately 8 minutes per creative, plus queue wait time. Use the status endpoint to poll for completion.

GET

/api/creative/:creativeId/statusAuth Required

Poll the processing status of a submitted creative. Returns detailed task status, completion percentage, and estimated time remaining.

URL Parameters

creativeIdstringRequiredThe unique identifier of the creative

Success Response

{
  "success": true,
  "data": {
    "creative_id": "creative-456",
    "overall_status": "processing",
    "completion_percentage": 60,
    "estimated_completion_time": "2025-10-22T10:28:00.000Z",
    "tasks": [
      {
        "task_type": "ad_render",
        "status": "success",
        "started_at": "2025-10-22T10:22:00.000Z",
        "completed_at": "2025-10-22T10:24:00.000Z",
        "duration_ms": 120000,
        "retry_count": 0
      },
      {
        "task_type": "adomain_capture",
        "status": "success",
        "started_at": "2025-10-22T10:24:00.000Z",
        "completed_at": "2025-10-22T10:25:00.000Z",
        "duration_ms": 60000,
        "retry_count": 0
      },
      {
        "task_type": "brand_mapping",
        "status": "success",
        "started_at": "2025-10-22T10:25:00.000Z",
        "completed_at": "2025-10-22T10:25:30.000Z",
        "duration_ms": 30000,
        "retry_count": 0
      },
      {
        "task_type": "adomain_analysis",
        "status": "processing",
        "started_at": "2025-10-22T10:25:30.000Z",
        "retry_count": 0
      },
      {
        "task_type": "ad_analysis",
        "status": "pending",
        "retry_count": 0
      }
    ],
    "last_activity": "2025-10-22T10:25:30.000Z",
    "created_at": "2025-10-22T10:22:00.000Z",
    "processing_started_at": "2025-10-22T10:22:00.000Z"
  },
  "meta": {
    "last_updated": "2025-10-22T10:26:00.000Z",
    "request_id": "req-xyz789"
  }
}

Status Values

pendingTask is queued but not started

processingTask is currently running

completedAll tasks completed successfully

failedOne or more tasks failed

Creative Retrieval

GET

/api/creative/:creativeIdAuth Required

Retrieve complete creative details including audit results, screenshots, IAB classifications, and quality scores.

URL Parameters

creativeIdstringRequiredThe unique identifier of the creative

Success Response

{
  "creative": {
    "id": "creative-456",
    "cur": "USD",
    "seatbid": [{
      "seat": "advertiser-seat",
      "bid": [{
        "id": "creative-456",
        "price": 2.5,
        "adm": "...",
        "adomain": ["example.com"],
        "w": 300,
        "h": 250
      }]
    }]
  },
  "audit": {
    "assets": {
      "screenshots": [
        "https://cdn.glos.si/creatives/creative-456/screenshot-1.jpg"
      ],
      "videos": [],
      "htmlPath": "https://cdn.glos.si/creatives/creative-456/rendered.html",
      "landingPageScreenshot": "https://cdn.glos.si/sites/example.com/screenshot.jpg"
    },
    "classification": {
      "iabCategories": [
        {
          "code": "IAB7",
          "name": "Health & Fitness",
          "description": "Health and fitness content"
        }
      ],
      "iabProducts": [
        {
          "id": 1,
          "name": "Skin Care",
          "tier1": "Personal Care",
          "tier2": "Beauty",
          "tier3": "Skin Care"
        }
      ]
    },
    "adQualityScore": 8.5,
    "summary": "Health and wellness product advertisement",
    "status": "completed"
  }
}

GET

/api/creativesAuth Required

Query and filter creatives with advanced filtering, pagination, and search capabilities.

Query Parameters

pagenumberPage number (default: 1)

limitnumberResults per page (max: 100, default: 20)

domainstring[]Filter by advertiser domains

seatstring[]Filter by seat IDs

statusstring[]Filter by status (pending, processing, completed, failed)

ad_formatstring[]Filter by ad format

dimensionsstringFilter by dimensions (e.g., "300x250")

submitted_afterISO 8601Filter by submission date

submitted_beforeISO 8601Filter by submission date

iab_categorystring[]Filter by IAB category codes

iab_productnumber[]Filter by IAB product IDs

searchstringText search across domains, seats, and summaries

includestring[]Include related data (tasks, audit_result, iab_categories, iab_products, tags, domains)

Example Request

curl -H "X-API-Key: your_api_key_here" \
  "https://glos.si/api/creatives?page=1&limit=20&status=completed&include=audit_result&include=iab_categories"

Success Response

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  },
  "meta": {
    "request_id": "req-def456",
    "processing_time_ms": 45,
    "query_params": {
      "page": 1,
      "limit": 20,
      "status": ["completed"]
    }
  }
}

Creative Management

POST

/api/reprocessAuth Required

Reprocess a creative with specific actions or refetch data bypassing cache.

Request Body

creativeIdstringRequiredThe creative ID to reprocess

actionstringSpecific task to reprocess (all, ad_render, adomain_capture, brand_mapping, ad_analysis, adomain_analysis, video_analysis, landing_page_capture)

refetchbooleanBypass cache and refetch data

Example Request

{
  "creativeId": "creative-456",
  "action": "ad_analysis",
  "refetch": true
}

Analytics & Statistics

GET

/api/statsAuth Required

Get aggregated advertising statistics including top domains, categories, and bid data.

Success Response

{
  "topDomains": [
    {
      "domain": "example.com",
      "count": 1500,
      "avgBid": 2.35
    }
  ],
  "topCategories": [...],
  "topSeats": [...],
  "topIabProducts": [...]
}

Error Handling

All endpoints return consistent error responses with the following structure:

Error Response Format

{
  "success": false,
  "error": "Error message",
  "details": "Detailed error description",
  "meta": {
    "request_id": "req-abc123"
  }
}

HTTP Status Codes

200Success - Request completed successfully

400Bad Request - Invalid parameters or request body

401Unauthorized - Missing or invalid authentication

404Not Found - Resource does not exist

500Internal Server Error - Server-side error occurred

Request Tracking

All requests include a unique request_id in the response meta. Include this ID when contacting support for faster resolution.

Support & Contact

Need Help?

Have questions about the API or need assistance with integration?

Contact Support