Skip to main content

​
Base URL

https://api-v2.tumban.com
All v2 endpoints are mounted under /api/v2.

​
Authentication

Every request requires an Authorization: Bearer <token> header. 
Authorization: Bearer sk_<64-hex-string>
See Authentication for the full description.

​
Content type

Request and response bodies are JSON. Send Content-Type: application/json on POST and PATCH.

​
Error envelope

Errors return a JSON object with a detail field: 
{ "detail": "Invalid or revoked API key" }
Validation errors (HTTP 422) return a list under detail. Each entry has loc (an array of segments locating the offending field), msg, type, and may include input, ctx, and url. 
{
  "detail": [
    {
      "loc": ["body", "profile_url"],
      "msg": "Input should be a valid URL",
      "type": "url_parsing",
      "input": "not-a-url"
    }
  ]
}
See Errors for the status-code reference.

​
Async processing

Endpoints that submit work (/scan/deep, /scan/quick, /batch/deep, /batch/quick) return immediately with a status of processing and an estimated completion time. The final result is delivered either by webhook to your callback_url or by polling GET /api/v2/scans/{scan_id}.

​
Tenancy

Every request is scoped to the organization that owns the credential. You cannot read or list resources from another organization.

​
Rate limits

Tumban enforces a per-organization daily scan limit when one is configured for your org. Scan-submission endpoints (Create scan, Create batch) return 429 with a structured detail body when the limit is hit: 
{
  "detail": {
    "error": "daily_scan_limit_exceeded",
    "limit": 1000,
    "used": 1000
  }
}
The counter resets at 00:00 UTC. Create batch has a partial-acceptance path — see its docs. Tumban does not return X-RateLimit-* headers, and it does not honour an Idempotency-Key header. Treat your scan_id (or per-profile scan_ids in a batch) as the natural idempotency key in your own handler.