{ "openapi": "3.1.0", "info": { "title": "AITWIRE API", "version": "1.0.0", "description": "The AITWIRE API enables developers to programmatically manage entities, run scans, query authority graphs, monitor drift, track attribution, and manage webhooks and API keys.\n\n## Authentication\nAll API requests require a Bearer token or X-API-Key header with an `atwk_*` API key.\n\n## Base URL\n`https://api.aitwire.com/v1/`\n\n## Rate Limits\n- Standard: 60 req/min, 1,000 calls/mo included\n- Pro: 300 req/min, 50,000 calls/mo included\n- AITWIRE AI: 1,000 req/min, contract-based", "contact": { "email": "developers@aitwire.com", "url": "https://developers.aitwire.com" } }, "servers": [ { "url": "https://api.aitwire.com/v1", "description": "Production" } ], "security": [ { "ApiKeyBearer": [] }, { "ApiKeyHeader": [] } ], "components": { "securitySchemes": { "ApiKeyBearer": { "type": "http", "scheme": "bearer", "description": "Bearer atwk_..." }, "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "X-API-Key: atwk_..." } }, "schemas": { "Error": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "ok", "error" ] }, "Entity": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "type": { "type": "string" }, "canonical_url": { "type": "string" }, "source": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "hash": { "type": "string" }, "version": { "type": "integer" }, "updated_at": { "type": "integer" } } }, "ScanRun": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "pages_scanned": { "type": "integer" }, "entities_found": { "type": "integer" } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key_prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" } } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" } } }, "UsageStats": { "type": "object", "properties": { "plan": { "type": "string" }, "included_requests": { "type": "integer" }, "overage_rate": { "type": "number" }, "overage_requests": { "type": "integer" }, "projected_overage_cost": { "type": "number" }, "total_requests": { "type": "integer" }, "daily": { "type": "array", "items": { "type": "object" } } } } }, "parameters": { "tenant": { "name": "tenant", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Tenant ID" } } }, "paths": { "/entities": { "get": { "operationId": "listEntities", "summary": "List entities", "tags": [ "Entities" ], "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Entity list", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } }, "next_cursor": { "type": "string" } } } } } } } } }, "/entities/{id}": { "get": { "operationId": "getEntity", "summary": "Get entity by ID", "tags": [ "Entities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "entity": { "$ref": "#/components/schemas/Entity" } } } } } } } }, "put": { "operationId": "upsertEntity", "summary": "Create or update entity", "tags": [ "Entities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tenant_id", "type", "canonical_url" ], "properties": { "tenant_id": { "type": "string" }, "type": { "type": "string" }, "canonical_url": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" } } } } } }, "responses": { "200": { "description": "Created/updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "action": { "type": "string" }, "id": { "type": "string" }, "version": { "type": "integer" } } } } } } } } }, "/scans": { "get": { "operationId": "listScans", "summary": "List scan runs", "tags": [ "Scans" ], "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "Scan list", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/ScanRun" } } } } } } } } } }, "/scans/run": { "post": { "operationId": "runScan", "summary": "Trigger a new scan", "tags": [ "Scans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tenant", "domain" ], "properties": { "tenant": { "type": "string" }, "domain": { "type": "string" } } } } } }, "responses": { "200": { "description": "Scan started", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "run_id": { "type": "string" } } } } } } } } }, "/authority/graph": { "get": { "operationId": "getAuthorityGraph", "summary": "Get authority graph", "tags": [ "Authority" ], "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "Authority graph" } } } }, "/governance/drift/events": { "get": { "operationId": "listDriftEvents", "summary": "List drift events", "tags": [ "Drift" ], "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "new", "ack", "resolved", "ignored" ] } } ], "responses": { "200": { "description": "Drift events" } } } }, "/attribution/summary": { "get": { "operationId": "getAttributionSummary", "summary": "Get AI attribution summary", "tags": [ "Attribution" ], "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } } ], "responses": { "200": { "description": "Attribution summary" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "Webhook list" } } }, "post": { "operationId": "createWebhook", "summary": "Create webhook endpoint", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "tenant" ], "properties": { "tenant": { "type": "string" }, "url": { "type": "string", "description": "Must be https:// and resolve to a public host — loopback, private/link-local ranges, non-standard ports and embedded credentials are rejected" }, "description": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" }, "default": [ "*" ] } } } } } }, "responses": { "200": { "description": "Webhook created with signing secret" } } } }, "/webhooks/{id}": { "patch": { "operationId": "updateWebhook", "summary": "Enable/disable or reconfigure a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" }, "url": { "type": "string", "description": "Must be https:// and resolve to a public host — loopback, private/link-local ranges, non-standard ports and embedded credentials are rejected" }, "description": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Webhook updated" }, "404": { "description": "No such endpoint for this tenant" } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook removed" }, "404": { "description": "No such endpoint for this tenant" } } } }, "/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Deliver a synthetic webhook.test event to one endpoint", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/tenant" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delivery attempted; body carries the endpoint's own status code" }, "404": { "description": "No such endpoint for this tenant" } } } }, "/keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys", "tags": [ "API Keys" ], "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "Key list" } } }, "post": { "operationId": "createApiKey", "summary": "Create API key", "tags": [ "API Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tenant_id" ], "properties": { "tenant_id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Fine-grained scopes (entities:read, scans:run, etc.) or legacy (read/write)" } } } } } }, "responses": { "201": { "description": "Key created (full key shown once)" } } } }, "/keys/scopes": { "get": { "operationId": "listAvailableScopes", "summary": "List available API key scopes", "tags": [ "API Keys" ], "responses": { "200": { "description": "Available scopes" } } } }, "/billing/usage": { "get": { "operationId": "getUsageStats", "summary": "Get API usage for current billing period", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/tenant" } ], "responses": { "200": { "description": "Usage statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageStats" } } } } } } } } }