{"openapi":"3.1.0","info":{"title":"TickAutoAI Paper Checking API","version":"1.0.0","description":"Submit two PDFs, poll a durable job, and retrieve marks, feedback, and annotations. All operations are organisation-scoped."},"servers":[{"url":"https://service.tickautoai.com"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/evaluations":{"post":{"operationId":"createEvaluation","summary":"Evaluate a student answer PDF against a model-answer PDF","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_.:\\-]+$"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["student_pdf","model_answer_pdf"],"properties":{"student_pdf":{"type":"string","format":"binary","description":"PDF, at most 20 MiB / 100 pages"},"model_answer_pdf":{"type":"string","format":"binary","description":"Complete descriptive rubric including explicit labels, question stems, answers and marks"},"student_name":{"type":"string","default":"Student","maxLength":150},"external_id":{"type":"string","maxLength":150},"checking_mode":{"type":"string","enum":["NORMAL","STRICT"],"default":"NORMAL"}}}}}},"responses":{"202":{"description":"Accepted, or replay of the original job","headers":{"Location":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer"},"description":"Suggested polling interval in seconds"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evaluation"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Evaluation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listEvaluations","summary":"List up to 50 evaluations in descending opaque ID order","parameters":[{"in":"query","name":"before","schema":{"type":"string"},"description":"Pass next_cursor from the previous page"}],"responses":{"200":{"description":"Evaluation page","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Evaluation"}},"next_cursor":{"type":["string","null"]}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Evaluation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/evaluations/{id}":{"get":{"operationId":"getEvaluation","summary":"Poll an evaluation or retrieve a completed result","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current evaluation state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evaluation"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Evaluation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/balance":{"get":{"operationId":"getBalance","summary":"Get available balance and the current per-job reservation","responses":{"200":{"description":"Available prepaid balance","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"const":"INR"},"available_paise":{"type":"integer","minimum":0,"description":"Amount in paise; 100 paise = INR 1"},"evaluation_reserve_paise":{"type":"integer","minimum":0,"description":"Amount in paise; 100 paise = INR 1"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Evaluation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Organisation API key, shown once when created in the console"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}},"Feedback":{"type":"object","required":["short","detailed"],"properties":{"short":{"type":"string"},"detailed":{"type":"string"}}},"Question":{"type":"object","required":["question_number","label","question_text","student_answer","marks_awarded","max_marks","feedback","confidence","needs_review","review_reasons"],"properties":{"question_number":{"type":"integer"},"label":{"type":"string"},"question_text":{"type":"string"},"student_answer":{"type":"string"},"marks_awarded":{"type":"number"},"max_marks":{"type":"number"},"feedback":{"$ref":"#/components/schemas/Feedback"},"confidence":{"type":"number"},"needs_review":{"type":"boolean"},"review_reasons":{"type":"array","items":{"type":"string"}}}},"Annotation":{"type":"object","required":["question_label","page_index","x","y","marks_awarded","max_marks","feedback"],"properties":{"question_label":{"type":"string"},"page_index":{"type":"integer","minimum":0},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1},"marks_awarded":{"type":"number"},"max_marks":{"type":"number"},"feedback":{"type":"string"}}},"Result":{"type":"object","required":["total_marks","max_marks","percentage","questions","annotations","annotation_status","needs_review","annotation_coordinates"],"properties":{"total_marks":{"type":"number"},"max_marks":{"type":"number"},"percentage":{"type":"number"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/Question"}},"annotations":{"type":"array","items":{"$ref":"#/components/schemas/Annotation"}},"annotation_status":{"type":"string","enum":["available","partial","unavailable"]},"needs_review":{"type":"boolean"},"annotation_coordinates":{"type":"object","properties":{"origin":{"const":"top-left"},"units":{"const":"normalized"},"page_index_base":{"const":0}}}}},"Evaluation":{"type":"object","required":["id","status","external_id","student_name","checking_mode","created_at","completed_at","billing","result","error","status_url"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","processing","completed","failed"]},"external_id":{"type":["string","null"]},"student_name":{"type":"string"},"checking_mode":{"type":"string","enum":["NORMAL","STRICT"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"billing":{"type":"object","properties":{"currency":{"const":"INR"},"reserved_paise":{"type":"integer","minimum":0,"description":"Amount in paise; 100 paise = INR 1"},"charged_paise":{"type":["integer","null"],"minimum":0,"description":"Amount in paise; 100 paise = INR 1"}}},"result":{"anyOf":[{"$ref":"#/components/schemas/Result"},{"type":"null"}]},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"status_url":{"type":"string"}}}}}}