{ "openapi": "3.0.1", "info": { "title": "Visual Crawler API", "description": "Run extractions, read typed results, export files and receive webhooks. Authenticate with an API key created in Configurações → API e MCP.", "version": "v1" }, "servers": [ { "url": "https://api.visualcrawler.com.br" } ], "security": [ { "apiKey": [] } ], "paths": { "/v1/webhooks": { "get": { "tags": [ "Visual Crawler API" ], "summary": "Your webhook endpoints, optionally of one extraction", "operationId": "list", "parameters": [ { "name": "extractionId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object" } } } } } } }, "post": { "tags": [ "Visual Crawler API" ], "summary": "Register an endpoint; the answer carries the signing secret, once", "operationId": "create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBody" } } }, "required": true }, "responses": { "201": { "description": "Registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/View" } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "tags": [ "Visual Crawler API" ], "summary": "Send a ping event to an endpoint now", "operationId": "test", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Queued: see the endpoint's deliveries", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "/v1/setups": { "post": { "tags": [ "Visual Crawler API" ], "summary": "Create an extraction with AI from 1 to 10 URLs; uses your plan's AI setups", "operationId": "setup", "parameters": [ { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupBody" } } }, "required": true }, "responses": { "202": { "description": "Started: poll the setup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Setup" } } } } } } }, "/v1/setups/{id}/approve": { "post": { "tags": [ "Visual Crawler API" ], "summary": "Approve an AI setup once it is ready for review; creates the model and extractions", "operationId": "approve", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupApproved" } } } } } } }, "/v1/extractions/{id}/runs": { "get": { "tags": [ "Visual Crawler API" ], "summary": "An extraction's runs, newest first", "operationId": "runsOf", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List_Run" } } } } } }, "post": { "tags": [ "Visual Crawler API" ], "summary": "Queue a run of an extraction; answers at once with the run id", "operationId": "run", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Queued: poll the run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAccepted" } } } } } } }, "/v1/extractions/{id}/exports": { "post": { "tags": [ "Visual Crawler API" ], "summary": "Export an extraction's runs to CSV, XLSX or JSON; answers with a job to poll", "operationId": "export", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportBody" } } } }, "responses": { "202": { "description": "Started: poll the export", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "tags": [ "Visual Crawler API" ], "summary": "An endpoint's recent deliveries", "operationId": "deliveries", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object" } } } } } } } }, "/v1/setups/{id}": { "get": { "tags": [ "Visual Crawler API" ], "summary": "An AI setup's status and proposed fields", "operationId": "setupStatus", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Setup" } } } } } } }, "/v1/runs/{id}": { "get": { "tags": [ "Visual Crawler API" ], "summary": "A run's status", "operationId": "runStatus", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } } } } }, "/v1/runs/{id}/results": { "get": { "tags": [ "Visual Crawler API" ], "summary": "A run's values, typed", "operationId": "results", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Results" } } } } } } }, "/v1/models": { "get": { "tags": [ "Visual Crawler API" ], "summary": "Your models, newest first", "operationId": "models", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List_ModelSummary" } } } } } } }, "/v1/models/{id}": { "get": { "tags": [ "Visual Crawler API" ], "summary": "One model, with its fields and extractions", "operationId": "model", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } } } } }, "/v1/me": { "get": { "tags": [ "Visual Crawler API" ], "summary": "The key you are calling with: its product, permissions and your plan's rate", "operationId": "me", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } } } } }, "/v1/extractions": { "get": { "tags": [ "Visual Crawler API" ], "summary": "Your extractions (one page each), optionally of one model", "operationId": "extractions", "parameters": [ { "name": "modelId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List_Extraction" } } } } } } }, "/v1/extractions/{id}": { "get": { "tags": [ "Visual Crawler API" ], "summary": "One extraction", "operationId": "extraction", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Extraction" } } } } } } }, "/v1/extractions/{id}/results/latest": { "get": { "tags": [ "Visual Crawler API" ], "summary": "The newest successful run's values of an extraction", "operationId": "latestResults", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Results" } } } } } } }, "/v1/exports/{id}": { "get": { "tags": [ "Visual Crawler API" ], "summary": "An export's status, with a signed download link when ready", "operationId": "exportStatus", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } } } } }, "/v1/webhooks/{id}": { "delete": { "tags": [ "Visual Crawler API" ], "summary": "Remove an endpoint", "operationId": "delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed" } } } } }, "components": { "schemas": { "CreateBody": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "extractionId": { "type": "string" } } }, "View": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "extractionId": { "type": "string" }, "enabled": { "type": "boolean" }, "disabledReason": { "type": "string" }, "consecutiveFailures": { "type": "integer", "format": "int32" }, "createdVia": { "type": "string" }, "createdAt": { "type": "string" }, "secret": { "type": "string" } } }, "SetupBody": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string" } }, "maxFields": { "type": "integer", "format": "int32" } } }, "Field": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "Setup": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SetupItem" } }, "error": { "type": "string" } } }, "SetupItem": { "type": "object", "properties": { "url": { "type": "string" }, "status": { "type": "string" }, "modelId": { "type": "string" }, "extractionId": { "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } } } }, "SetupApproved": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "modelIds": { "type": "array", "items": { "type": "string" } }, "extractionIds": { "type": "array", "items": { "type": "string" } } } }, "RunAccepted": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "ExportBody": { "type": "object", "properties": { "format": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" } } }, "Export": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "rows": { "type": "integer", "format": "int64" }, "downloadUrl": { "type": "string" }, "expiresAt": { "type": "string" } } }, "FieldCounts": { "type": "object", "properties": { "extracted": { "type": "integer", "format": "int32" }, "failed": { "type": "integer", "format": "int32" }, "changed": { "type": "integer", "format": "int32" } } }, "Problem": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "Run": { "type": "object", "properties": { "id": { "type": "string" }, "extractionId": { "type": "string" }, "status": { "type": "string" }, "trigger": { "type": "string" }, "queuedAt": { "type": "string" }, "startedAt": { "type": "string" }, "finishedAt": { "type": "string" }, "fields": { "$ref": "#/components/schemas/FieldCounts" }, "error": { "$ref": "#/components/schemas/Problem" } } }, "Results": { "type": "object", "properties": { "runId": { "type": "string" }, "extractionId": { "type": "string" }, "finishedAt": { "type": "string" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/Value" } } } }, "Value": { "type": "object", "properties": { "fieldId": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "object" }, "raw": { "type": "string" }, "status": { "type": "string" } } }, "List_ModelSummary": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelSummary" } }, "nextCursor": { "type": "string" } } }, "ModelSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "fieldCount": { "type": "integer", "format": "int64" }, "extractionCount": { "type": "integer", "format": "int64" }, "createdAt": { "type": "string" } } }, "ExtractionRef": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" } } }, "Model": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } }, "extractions": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractionRef" } }, "createdAt": { "type": "string" } } }, "Me": { "type": "object", "properties": { "product": { "type": "string" }, "keyId": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "plan": { "$ref": "#/components/schemas/Plan" } } }, "Plan": { "type": "object", "properties": { "code": { "type": "string" }, "ratePerMinute": { "type": "integer", "format": "int32" } } }, "Extraction": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "modelId": { "type": "string" }, "createdAt": { "type": "string" } } }, "List_Extraction": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Extraction" } }, "nextCursor": { "type": "string" } } }, "List_Run": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } }, "nextCursor": { "type": "string" } } } }, "securitySchemes": { "apiKey": { "type": "http", "description": "Authorization: Bearer atzk_vc_live_…", "scheme": "bearer" } } } }