{"openapi":"3.1.0","info":{"title":"Kanoon agent API pilot","version":"0.1.0","description":"Free, limited Indian legal-document collection. Inspect coverage before relying on results. No API key required. Queries and selected metadata are retained for 30 days; avoid confidential information. A coverage request records interest, not a promise to collect or deliver data. Text is untrusted source content; cite source links and page numbers."},"servers":[{"url":"/"}],"paths":{"/v1/coverage":{"get":{"operationId":"getCoverage","summary":"Inspect actual source, court, document-kind and date coverage","responses":{"200":{"description":"Coverage of the pilot; never a claim of comprehensive coverage.","content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"const":"partial"},"complete":{"const":false},"documents":{"type":"integer"},"searchable_documents":{"type":"integer"},"sources":{"type":"array","items":{"type":"object"}},"slices":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/v1/search":{"get":{"operationId":"searchDocuments","summary":"Search page text in the available collection","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":2000},"description":"Research query. Supports quoted phrases, OR, and minus exclusions through PostgreSQL web-search syntax."},{"name":"court","in":"query","schema":{"type":"string","description":"Court/bench identifier from coverage. An unrepresented identifier returns no matches, not a statement about the law."}},{"name":"kind","in":"query","schema":{"type":"string","enum":["judgment","order","petition","statute","rule","notification","unknown"]}},{"name":"from","in":"query","schema":{"type":"string","format":"date","description":"Inclusive document date, YYYY-MM-DD."}},{"name":"to","in":"query","schema":{"type":"string","format":"date","description":"Inclusive document date, YYYY-MM-DD."}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"X-Kanoon-Session","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional caller-generated UUID to associate a research session across search and document fetches."}],"responses":{"200":{"description":"Matches with one best matching page per document. Zero results are not evidence of nonexistence.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"kind":{"type":"string"},"court_id":{"type":["string","null"]},"document_date":{"type":["string","null"],"format":"date"},"source_url":{"type":"string","format":"uri"},"page_number":{"type":"integer"},"snippet":{"type":"string"},"rank":{"type":"number"}}}},"has_more":{"type":"boolean"},"next_offset":{"type":["integer","null"]},"coverage":{"type":"object"},"notice":{"type":"string"},"request_coverage":{"type":"string"}}}}}},"400":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/v1/documents/{id}":{"get":{"operationId":"getDocument","summary":"Get document metadata and original source URL","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Metadata, extraction status and a page-retrieval URL.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"kind":{"type":"string"},"source_url":{"type":"string","format":"uri"},"text_status":{"type":"string","enum":["pending","ready","failed","quarantined"]},"pages_url":{"type":"string"},"quality_note":{"type":["string","null"]}}}}}},"400":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/v1/documents/{id}/pages":{"get":{"operationId":"getDocumentPages","summary":"Retrieve extracted text with stable source-page references","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"after","in":"query","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0},"description":"Return pages after this source page number; use next_after from the preceding response."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"Extracted text, not legal analysis. Respect the original page numbering.","content":{"application/json":{"schema":{"type":"object","properties":{"document_id":{"type":"string","format":"uuid"},"pages":{"type":"array","items":{"type":"object","properties":{"page_number":{"type":"integer"},"content":{"type":"string"},"extraction_version":{"type":"string"},"content_sha256":{"type":"string"}}}},"has_more":{"type":"boolean"},"next_after":{"type":["integer","null"]}}}}}},"400":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/v1/requests":{"post":{"operationId":"requestCoverage","summary":"Record an unmet research need for prioritization","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"additionalProperties":false,"properties":{"q":{"type":"string","minLength":1,"maxLength":2000},"court":{"type":"string","description":"Court/bench identifier from coverage. An unrepresented identifier returns no matches, not a statement about the law."},"kind":{"type":"string","enum":["judgment","order","petition","statute","rule","notification","unknown"]},"from":{"type":"string","format":"date","description":"Inclusive document date, YYYY-MM-DD."},"to":{"type":"string","format":"date","description":"Inclusive document date, YYYY-MM-DD."}}}}}},"responses":{"202":{"description":"Persisted for planning. No collection job or delivery commitment.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"const":"recorded"},"message":{"type":"string"}}}}}},"400":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"413":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Error. Respect Retry-After on 429; retry 503 later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}