API Reference

Authentication

All API requests require a Bearer token in the Authorization header. Get your API key from Dashboard → API Keys.

Authorization: Bearer at_live_xK9mR2jQ4VnP8wBz3LsFhYcXd7tNgAeM

• API keys are tenant-scoped — they can access all resources within your organization but no others.
• Rotate keys in Dashboard → API Keys if a key is compromised. Old keys are immediately invalidated on rotation.
• Test vs. live keys: Test keys (prefixed at_test_) do not consume credits and return synthetic data. Use for development and CI.

Base URL

https://app.avidiatech.com/api/v1

All endpoints are relative to this base URL. The API version is v1. Breaking changes will increment the version.

Rate Limits

Rate limit status is returned in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix timestamp). On 429, use the Retry-After header value (seconds).

Error Format

// All errors use this shape:
{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",   // optional
  "details": { ... }                 // optional, for validation errors
}

// Example: missing required field
HTTP 400 Bad Request
{
  "error": "Missing required field: url",
  "code": "MISSING_FIELD",
  "details": { "field": "url" }
}

Pagination

List endpoints support limit (max 100, default 20) and offset (default 0) query parameters.

GET /api/v1/ingest?limit=50&offset=100

// Response envelope
{
  "data": [ ... ],
  "total": 843,
  "limit": 50,
  "offset": 100
}

POST /ingest — Submit a Product URL

Submits a product URL for extraction. Returns immediately with a queued status. Use the returned ID to poll for results or set up a webhook.

POST /api/v1/ingest
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "url": "https://www.boschtools.com/us/en/boschtools-ocs/cordless-drill-GSB-18V-755.html",
  "options": {
    "reprocess": false,
    "pipeline": ["extract", "describe", "seo"]
  }
}

// 202 Accepted
{
  "id": "ing_01HX4K2QZRP7W9VMBGT3DENF8",
  "status": "queued",
  "created_at": "2024-03-15T14:22:00.000Z",
  "url": "https://www.boschtools.com/..."
}

GET /ingest/:id — Get Extraction Result

Retrieves the current status and data for an ingestion. Poll until status is complete or failed.

GET /api/v1/ingest/ing_01HX4K2QZRP7W9VMBGT3DENF8
Authorization: Bearer <api-key>

// 200 OK
{
  "id": "ing_01HX4K2QZRP7W9VMBGT3DENF8",
  "status": "complete",
  "score": 87,
  "extracted_data": {
    "product_name": "Bosch GSB 18V-755 Cordless Combi Drill",
    "brand": "Bosch",
    "sku": "06019H3110",
    "specifications": {
      "max_torque": "75 Nm",
      "chuck_size": "13 mm",
      "speed_1": "0-550 rpm",
      "speed_2": "0-2100 rpm",
      "battery": "18V Li-ion"
    },
    "images": [
      "https://media.bosch-pt.com/media/A_37888.jpg"
    ],
    "availability": "in_stock",
    "price": "189.00"
  },
  "created_at": "2024-03-15T14:22:00.000Z",
  "completed_at": "2024-03-15T14:22:14.832Z"
}

POST /describe — Generate Description

POST /api/v1/describe
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "ingestion_id": "ing_01HX4K2QZRP7W9VMBGT3DENF8",
  "tone": "professional",
  "format": "html",
  "length": "standard",
  "custom_instructions": "Highlight the BITURBO brushless motor."
}

// 200 OK
{
  "id": "desc_01HX5QRTAB2N3VMCGP4REEF9",
  "ingestion_id": "ing_01HX4K2QZRP7W9VMBGT3DENF8",
  "short": "Professional-grade brushless combi drill with 75 Nm torque, ideal for concrete and masonry on a single 18V charge.",
  "long": "<p>The Bosch GSB 18V-755 is engineered for professionals who need...</p>",
  "bullets": [
    "BITURBO brushless motor delivers 75 Nm hard torque",
    "2-speed gearbox: 0–550 rpm drilling / 0–2,100 rpm driving",
    "13mm keyless chuck for fast bit changes",
    "25+1 torque settings for precision screw driving",
    "Compatible with all Bosch 18V ProCORE batteries"
  ],
  "technical_summary": "GSB 18V-755 | Brushless EC | 75 Nm | 13mm chuck | 2-speed | 18V",
  "credits_used": 1
}

Tone options: professional, casual, technical, medical. Format options: html, markdown, plain.

POST /seo — Run SEO Optimization

POST /api/v1/seo
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "ingestion_id": "ing_01HX4K2QZRP7W9VMBGT3DENF8",
  "options": {
    "include_schema": true
  }
}

// 200 OK
{
  "id": "seo_01HX5MNQ2R4VP8XWBCJT5GAEF",
  "ingestion_id": "ing_01HX4K2QZRP7W9VMBGT3DENF8",
  "title": "18V Cordless Drill — Bosch GSB 18V-755 | Brushless Combi",
  "meta_description": "Shop the Bosch GSB 18V-755 cordless combi drill — 75 Nm brushless motor, 13mm chuck, 25+1 torque settings. Professional-grade power for concrete and wood.",
  "h1": "Bosch GSB 18V-755 Cordless Combi Drill (18V)",
  "schema": {
    "@context": "https://schema.org/",
    "@type": "Product",
    "name": "Bosch GSB 18V-755 Cordless Combi Drill",
    "brand": { "@type": "Brand", "name": "Bosch" },
    "sku": "06019H3110"
  },
  "score": 91,
  "recommendations": [],
  "credits_used": 1
}

POST /bulk — Create Bulk Job

Submit multiple URLs in a single request. The job runs asynchronously — poll GET /api/v1/bulk/:id for progress.

POST /api/v1/bulk
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "urls": [
    "https://www.3m.com/3M/en_US/p/d/v000057867/",
    "https://www.boschtools.com/us/en/.../GSB-18V-755.html",
    "https://www.medline.com/product/SensiCare-Gloves/Z05-PF18255"
  ],
  "pipeline": ["extract", "describe", "seo"]
}

// 202 Accepted
{
  "id": "bulk_01HX6PQRS3VP9YWCDJT6HAEG",
  "status": "processing",
  "total_items": 3,
  "created_at": "2024-03-15T15:00:00.000Z"
}

GET /bulk/:id — Get Bulk Job Status

GET /api/v1/bulk/bulk_01HX6PQRS3VP9YWCDJT6HAEG
Authorization: Bearer <api-key>

// 200 OK (in progress)
{
  "id": "bulk_01HX6PQRS3VP9YWCDJT6HAEG",
  "status": "processing",
  "total": 3,
  "processed": 2,
  "succeeded": 2,
  "failed": 0,
  "estimated_completion": "2024-03-15T15:02:30.000Z"
}

// 200 OK (complete)
{
  "id": "bulk_01HX6PQRS3VP9YWCDJT6HAEG",
  "status": "complete",
  "total": 3,
  "processed": 3,
  "succeeded": 3,
  "failed": 0,
  "ingestion_ids": [
    "ing_01HX4K2QZRP7W9VMBGT3DENF8",
    "ing_01HX4K9ZTAB2N3VMCGP4REEF9",
    "ing_01HX4KBMN4CD5WOPDHQ7SGFH2"
  ],
  "completed_at": "2024-03-15T15:02:18.441Z"
}