{"openapi":"3.1.0","info":{"title":"Geo Lead API","version":"1.0.0","description":"Versioned API for Geo Lead paid subscribers. Designed for server integrations, AI agents and future MCP tools."},"servers":[{"url":"/api/v1"}],"security":[{"bearerApiKey":[]}],"paths":{"/":{"get":{"operationId":"discoverApi","security":[],"summary":"Discover the API and its OpenAPI document","responses":{"200":{"description":"API discovery document"}}}},"/openapi.json":{"get":{"operationId":"getOpenApiDocument","security":[],"summary":"Get the machine-readable OpenAPI document","responses":{"200":{"description":"OpenAPI 3.1 document"}}}},"/me":{"get":{"operationId":"getApiIdentity","summary":"Inspect the authenticated account and key","x-required-scope":"usage:read","responses":{"200":{"description":"Authenticated API identity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/usage":{"get":{"operationId":"getApiUsage","summary":"Get 30-day API usage, credits and access status","x-required-scope":"usage:read","responses":{"200":{"description":"Usage summary"}}}},"/searches":{"get":{"operationId":"listSearches","summary":"List Instant Searches","x-required-scope":"searches:read","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Cursor-paginated searches"}}},"post":{"operationId":"createSearch","summary":"Create and count an Instant Search","x-required-scope":"searches:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"201":{"description":"Search created"},"400":{"$ref":"#/components/responses/InvalidRequest"}}}},"/searches/{searchId}":{"get":{"operationId":"getSearch","summary":"Get an Instant Search and current result count","x-required-scope":"searches:read","parameters":[{"$ref":"#/components/parameters/SearchId"}],"responses":{"200":{"description":"Search"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/searches/{searchId}/results":{"get":{"operationId":"listUnlockedSearchResults","summary":"List results already unlocked for a search","description":"Only results previously unlocked with Geo Lead credits are returned.","x-required-scope":"searches:read","parameters":[{"$ref":"#/components/parameters/SearchId"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Cursor-paginated unlocked lead DTOs"}}}},"/searches/{searchId}/exports":{"post":{"operationId":"createExport","summary":"Unlock additional results and queue an export","description":"Consumes the same Geo Lead credits as the web application. Reusing an Idempotency-Key never creates another debit.","x-required-scope":"exports:write","parameters":[{"$ref":"#/components/parameters/SearchId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["additional_results"],"properties":{"additional_results":{"type":"integer","minimum":1,"maximum":50000}}}}}},"responses":{"202":{"description":"Export queued"},"409":{"description":"Insufficient credits, results or conflicting idempotency key"}}}},"/exports":{"get":{"operationId":"listExports","summary":"List export jobs","x-required-scope":"exports:read","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Cursor-paginated exports"}}}},"/exports/{exportId}":{"get":{"operationId":"getExport","summary":"Get export job status","x-required-scope":"exports:read","parameters":[{"$ref":"#/components/parameters/ExportId"}],"responses":{"200":{"description":"Export status"}}}},"/exports/{exportId}/results":{"get":{"operationId":"listExportResults","summary":"List unlocked export results as JSON","x-required-scope":"exports:read","parameters":[{"$ref":"#/components/parameters/ExportId"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Cursor-paginated lead DTOs"},"409":{"description":"Export is not ready"}}}},"/exports/{exportId}/retry":{"post":{"operationId":"retryFailedExport","summary":"Retry a failed export without consuming credits","description":"This operation is idempotent by resource state: a queued, processing or ready export is returned unchanged.","x-required-scope":"exports:write","parameters":[{"$ref":"#/components/parameters/ExportId"}],"responses":{"200":{"description":"Export was already not failed"},"202":{"description":"Failed export queued again"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/exports/{exportId}/download":{"get":{"operationId":"downloadExport","summary":"Download a ready export archive","x-required-scope":"exports:read","parameters":[{"$ref":"#/components/parameters/ExportId"}],"responses":{"200":{"description":"ZIP archive"}}}},"/exports/{exportId}/custom-download":{"post":{"operationId":"downloadCustomExport","summary":"Download a ready export with selected authorized columns","x-required-scope":"exports:read","parameters":[{"$ref":"#/components/parameters/ExportId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Custom export archive"}}}},"/extractions/drafts":{"post":{"operationId":"createExtractionDraft","summary":"Create a Custom Extraction draft without consuming a launch","x-required-scope":"extractions:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Extraction draft"}}}},"/extractions":{"get":{"operationId":"listExtractions","summary":"List Custom Extractions","x-required-scope":"extractions:read","responses":{"200":{"description":"Extraction jobs"}}},"post":{"operationId":"createExtraction","summary":"Launch a Custom Extraction","x-required-scope":"extractions:write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractionRequest"}}}},"responses":{"201":{"description":"Extraction accepted"},"409":{"description":"Extraction capability or quota unavailable"}}}},"/extractions/{extractionId}/draft":{"patch":{"operationId":"updateExtractionDraft","summary":"Update an editable Custom Extraction draft","x-required-scope":"extractions:write","parameters":[{"$ref":"#/components/parameters/ExtractionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated extraction draft"}}}},"/extractions/{extractionId}/launch":{"post":{"operationId":"launchExtractionDraft","summary":"Launch a saved Custom Extraction draft","x-required-scope":"extractions:write","parameters":[{"$ref":"#/components/parameters/ExtractionId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Extraction accepted"}}}},"/extractions/{extractionId}":{"get":{"operationId":"getExtraction","summary":"Get extraction status","x-required-scope":"extractions:read","parameters":[{"$ref":"#/components/parameters/ExtractionId"}],"responses":{"200":{"description":"Extraction status"}}},"patch":{"operationId":"updateExtractionState","summary":"Pause or resume an extraction","x-required-scope":"extractions:write","parameters":[{"$ref":"#/components/parameters/ExtractionId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Updated extraction status"}}}},"/extractions/{extractionId}/results":{"get":{"operationId":"listExtractionResults","summary":"List live or archived extraction results","x-required-scope":"extractions:read","parameters":[{"$ref":"#/components/parameters/ExtractionId"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Extraction results"}}}},"/extractions/{extractionId}/stop":{"post":{"operationId":"stopExtraction","summary":"Stop an extraction","x-required-scope":"extractions:write","parameters":[{"$ref":"#/components/parameters/ExtractionId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Stopped extraction status"}}}}},"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gl_live API key","description":"Create a scoped API key in the Geo Lead account page. Never embed it in browser code."}},"parameters":{"Cursor":{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},"Limit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},"SearchId":{"name":"searchId","in":"path","required":true,"schema":{"type":"string"}},"ExportId":{"name":"exportId","in":"path","required":true,"schema":{"type":"string"}},"ExtractionId":{"name":"extractionId","in":"path","required":true,"schema":{"type":"string"}}},"responses":{"Unauthorized":{"description":"Missing, malformed, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Inactive subscription, suspended data access or insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidRequest":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found or not owned by the authenticated account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}}}}},"SearchItem":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","maxLength":160},"queryNames":{"type":"array","items":{"type":"string"},"maxItems":30},"localisationType":{"type":"string"},"localisationIdentifiers":{"type":"array","items":{"type":"string"},"maxItems":200}}},"SearchRequest":{"type":"object","additionalProperties":false,"required":["activities","countries","localisations"],"properties":{"activities":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/SearchItem"}},"countries":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/SearchItem"}},"localisations":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/SearchItem"}},"result_filter":{"type":"object"}}},"ExtractionRequest":{"type":"object","required":["categories","countries","localisations","enrichment_sources"],"properties":{"categories":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"type":"string"}},"localisations":{"type":"array","items":{"type":"string"}},"urls":{"type":"array","items":{"type":"string","format":"uri"}},"enrichment_sources":{"type":"array","items":{"type":"string"}},"serp_config":{"type":"object"}}}}}}