{"openapi":"3.1.0","info":{"title":"Crawdar Public API","version":"1.5.0","description":"Evidence-backed public business discovery for people and AI agents. Run a direct search or create a resumable job with compact pagination, refinement, caching, and CSV or JSON export. Free usage is rate limited."},"servers":[{"url":"https://crawdar.com"}],"paths":{"/api/v1/search":{"post":{"operationId":"searchBusinesses","summary":"Find businesses and their source evidence","security":[{},{"AgentKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Completed search","headers":{"x-request-id":{"schema":{"type":"string"}},"ratelimit-limit":{"schema":{"type":"integer"}},"ratelimit-remaining":{"schema":{"type":"integer"}},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until reset."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Invalid search brief","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Free usage or provider capacity reached","headers":{"x-request-id":{"schema":{"type":"string"}},"ratelimit-limit":{"schema":{"type":"integer"}},"ratelimit-remaining":{"schema":{"type":"integer"}},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until reset."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"A public web source did not respond","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/keys":{"post":{"operationId":"createAgentKey","summary":"Create a free agent API key","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"label":{"type":"string","maxLength":80}}}}}},"responses":{"201":{"description":"Key created. The secret is shown once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKeyResponse"}}}},"429":{"description":"Daily key issuance limit reached","headers":{"x-request-id":{"schema":{"type":"string"}},"ratelimit-limit":{"schema":{"type":"integer"}},"ratelimit-remaining":{"schema":{"type":"integer"}},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until reset."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"getAgentKeyUsage","summary":"Read the current key and quota usage","security":[{"AgentKey":[]}],"responses":{"200":{"description":"Key metadata and current usage","headers":{"x-request-id":{"schema":{"type":"string"}},"ratelimit-limit":{"schema":{"type":"integer"}},"ratelimit-remaining":{"schema":{"type":"integer"}},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until reset."}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/searches":{"post":{"operationId":"startLeadSearch","summary":"Create a resumable lead-search job from one brief","security":[{},{"AgentKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchJobRequest"}}}},"responses":{"201":{"description":"Search job completed from cache","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchJobEnvelope"}}}},"202":{"description":"Search job accepted and running asynchronously","headers":{"retry-after":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchJobEnvelope"}}}},"400":{"description":"Invalid lead brief","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Free usage or provider capacity reached","headers":{"x-request-id":{"schema":{"type":"string"}},"ratelimit-limit":{"schema":{"type":"integer"}},"ratelimit-remaining":{"schema":{"type":"integer"}},"ratelimit-reset":{"schema":{"type":"integer"},"description":"Seconds until reset."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/searches/{id}":{"get":{"operationId":"getLeadSearch","summary":"Page through compact or full search-job results","security":[{"JobToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"view","in":"query","schema":{"enum":["compact","full"],"default":"compact"}}],"responses":{"200":{"description":"A page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchJobPage"}}}},"202":{"description":"Job is not complete yet","headers":{"retry-after":{"schema":{"type":"integer"}}}},"404":{"description":"Job or capability token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/searches/{id}/refine":{"post":{"operationId":"refineLeadSearch","summary":"Create a new job by changing an existing search brief","security":[{"JobToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchJobRefinement"}}}},"responses":{"201":{"description":"Refined search job completed from cache","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchJobEnvelope"}}}},"202":{"description":"Refined search job accepted and running asynchronously","headers":{"retry-after":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchJobEnvelope"}}}}}}},"/api/v1/searches/{id}/retry":{"post":{"operationId":"retryLeadSearch","summary":"Create a replacement for a failed or expired search job","security":[{"JobToken":[],"AgentKey":[]},{"JobToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Replacement completed from cache","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchJobEnvelope"}}}},"202":{"description":"Replacement accepted and running","headers":{"retry-after":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchJobEnvelope"}}}},"409":{"description":"The original job is completed or still running"}}}},"/api/v1/searches/{id}/export":{"get":{"operationId":"exportLeadSearch","summary":"Download all job results as CSV or JSON","security":[{"JobToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","schema":{"enum":["csv","json"],"default":"csv"}}],"responses":{"200":{"description":"Complete result export"},"404":{"description":"Completed job not found"}}}}},"components":{"securitySchemes":{"AgentKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Optional free agent identity from POST /api/v1/keys."},"JobToken":{"type":"apiKey","in":"header","name":"x-job-token","description":"Capability token returned once with a search job."}},"schemas":{"SearchRequest":{"type":"object","required":["target","geography"],"additionalProperties":false,"properties":{"target":{"type":"string","minLength":3,"maxLength":220},"geography":{"type":"string","minLength":2,"maxLength":140},"qualifier":{"type":"string","maxLength":900,"description":"Optional public-evidence requirements. Missing evidence remains unverified."},"fields":{"type":"array","items":{"enum":["Website","Business email","Phone","Location","Owner type","Description","Source links"]}}}},"Evidence":{"type":"object","required":["label","url","kind"],"properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri"},"kind":{"type":"string"}}},"QualificationCheck":{"type":"object","required":["requirement","status","excerpt","sourceUrl"],"properties":{"requirement":{"type":"string"},"status":{"enum":["passed","failed","unverified"]},"excerpt":{"type":"string"},"sourceUrl":{"type":"string"}}},"Result":{"type":"object","required":["name","fitStatus","entityConfidence","qualificationConfidence","evidence","qualificationChecks"],"properties":{"name":{"type":"string"},"website":{"type":"string"},"websiteUrl":{"type":"string"},"city":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"fitStatus":{"enum":["verified","likely"],"description":"Verified means every requested qualification check passed. Likely means at least one check is open or unverified."},"confidence":{"type":"integer","minimum":0,"maximum":100},"entityConfidence":{"type":"integer","minimum":0,"maximum":100},"qualificationConfidence":{"type":"integer","minimum":0,"maximum":100},"evidenceQuality":{"enum":["strong","moderate","weak"]},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/Evidence"}},"qualificationChecks":{"type":"array","items":{"$ref":"#/components/schemas/QualificationCheck"}}}},"Diagnostics":{"type":"object","required":["discoveredCandidates","inspectedCandidates","acceptedResults","verifiedResults","likelyResults","rejectedCandidates","sourceStatus"],"properties":{"discoveredCandidates":{"type":"integer"},"inspectedCandidates":{"type":"integer"},"acceptedResults":{"type":"integer"},"verifiedResults":{"type":"integer"},"likelyResults":{"type":"integer"},"rejectedCandidates":{"type":"array","items":{"type":"object","required":["name","url","reason"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"reason":{"type":"string"}}}},"sourceStatus":{"type":"array","items":{"type":"object","required":["source","status","detail"],"properties":{"source":{"type":"string"},"status":{"enum":["complete","partial","failed"]},"detail":{"type":"string"}}}},"providerRequests":{"type":"object","required":["attempted","succeeded","failed","denied"],"properties":{"attempted":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"denied":{"type":"integer"}}}}},"SearchResponse":{"type":"object","required":["schemaVersion","requestId","results","resultCount","searchedSources","warnings","diagnostics"],"properties":{"schemaVersion":{"type":"string","example":"2026-08-22"},"requestId":{"type":"string"},"resultCount":{"type":"integer"},"durationMs":{"type":"integer"},"remainingFreeSearches":{"type":"integer"},"searchedSources":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"diagnostics":{"$ref":"#/components/schemas/Diagnostics"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Result"}}}},"SearchJobRequest":{"type":"object","additionalProperties":false,"properties":{"brief":{"type":"string","minLength":8,"maxLength":500,"description":"One natural-language lead brief. Geography and public-evidence requirements may be included."},"target":{"type":"string","minLength":3,"maxLength":220},"geography":{"type":"string","minLength":2,"maxLength":140},"qualifier":{"type":"string","maxLength":900},"fields":{"type":"array","items":{"enum":["Website","Business email","Phone","Location","Owner type","Description","Source links"]}},"sources":{"type":"array","items":{"type":"string"}},"limit":{"type":"integer","minimum":1,"maximum":50,"default":50}},"anyOf":[{"required":["brief"]},{"required":["target","geography"]}]},"SearchJobRefinement":{"type":"object","additionalProperties":false,"properties":{"brief":{"type":"string","minLength":8,"maxLength":500},"target":{"type":"string","minLength":3,"maxLength":220},"geography":{"type":"string","minLength":2,"maxLength":140},"qualifier":{"type":"string","maxLength":900},"fields":{"type":"array","items":{"type":"string"}},"limit":{"type":"integer","minimum":1,"maximum":50}}},"SearchJobEnvelope":{"type":"object","required":["id","status","jobToken","statusUrl","exportUrl","retryUrl","expiresInSeconds"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"enum":["queued","running","completed","failed"]},"jobToken":{"type":"string","description":"Shown once. Send it in x-job-token for subsequent requests."},"statusUrl":{"type":"string","format":"uri"},"exportUrl":{"type":"string","format":"uri"},"retryUrl":{"type":"string","format":"uri"},"expiresInSeconds":{"type":"integer"},"cacheHit":{"type":"boolean"},"resultCount":{"type":"integer"}}},"SearchJobPage":{"type":"object","required":["id","status","resultCount","returned","results"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"enum":["queued","running","completed","failed"]},"schemaVersion":{"type":"string"},"resultCount":{"type":"integer"},"returned":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Result"}},"nextCursor":{"type":["string","null"]},"diagnostics":{"$ref":"#/components/schemas/Diagnostics"},"warnings":{"type":"array","items":{"type":"string"}},"searchedSources":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}},"AgentKeyResponse":{"type":"object","required":["apiKey","key","message","requestId"],"properties":{"apiKey":{"type":"string","description":"Secret shown once."},"key":{"type":"object","additionalProperties":true},"message":{"type":"string"},"requestId":{"type":"string"}}},"ErrorResponse":{"type":"object","required":["schemaVersion","requestId","error","errorCode"],"properties":{"schemaVersion":{"type":"string"},"requestId":{"type":"string"},"error":{"type":"string"},"errorCode":{"type":"string"}}}}}}