{"openapi":"3.0.3","info":{"title":"Forenbench Evaluation API","version":"1.4.0","description":"One evaluation key authorizes only the selected questions in a single 24-hour evaluation. Verification consumes an attempt. Reference answers are never returned. Model identity is user-declared. Requires an agent with HTTP and file-analysis tools. Supports dedicated benchmark suites and entitlement-checked question-bank evaluations. Session includes user-provided execution environment; local evidence must be prepared by the user. Model-call usage is agent-reported, never inferred from evaluation HTTP requests. Unknown token usage remains null. Model identity is not verified. Completed rankings separate identical question snapshots and attempt limits; sharing is owner opt-in."},"servers":[{"url":"https:\/\/www.digiforensics.cn\/api\/forenbench\/v1"}],"security":[{"evaluationKey":[]}],"paths":{"\/session":{"get":{"operationId":"getEvaluation","summary":"Fetch evaluation rules and selected questions","responses":{"200":{"description":"Successful response","content":{"application\/json":{"schema":{"type":"object","properties":{"environment":{"type":"object","nullable":true,"properties":{"artifact_paths":{"type":"string","nullable":true},"mounts":{"type":"string","nullable":true},"tools":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}}}}}}}},"401":{"description":"Key invalid, expired or revoked"},"403":{"description":"Account or AI module access denied"},"404":{"description":"Question not in this evaluation"},"409":{"description":"Evaluation ended, question disabled or attempt limit reached"},"422":{"description":"Invalid request"},"429":{"description":"Rate limit; respect Retry-After"}}}},"\/questions\/{question}":{"get":{"operationId":"getQuestion","summary":"Fetch a selected question and remaining attempts","responses":{"200":{"description":"Successful response","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"description":"Key invalid, expired or revoked"},"403":{"description":"Account or AI module access denied"},"404":{"description":"Question not in this evaluation"},"409":{"description":"Evaluation ended, question disabled or attempt limit reached"},"422":{"description":"Invalid request"},"429":{"description":"Rate limit; respect Retry-After"}},"parameters":[{"name":"question","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Question ID returned by session; not an original training-bank ID."}]}},"\/questions\/{question}\/answers":{"post":{"operationId":"submitAnswer","summary":"Grade and record an answer; consumes an attempt","responses":{"200":{"description":"Successful response","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"description":"Key invalid, expired or revoked"},"403":{"description":"Account or AI module access denied"},"404":{"description":"Question not in this evaluation"},"409":{"description":"Evaluation ended, question disabled or attempt limit reached"},"422":{"description":"Invalid request"},"429":{"description":"Rate limit; respect Retry-After"}},"parameters":[{"name":"question","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Question ID returned by session; not an original training-bank ID."}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["request_id","answer"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Reuse this UUID only for retries of the same answer to this question."},"answer":{"oneOf":[{"type":"string","maxLength":10000},{"type":"array","maxItems":100,"items":{"type":"string","maxLength":200}}],"description":"Single choice\/true-false: option key. Fill blank: exact answer string. Multiple choice: array of option keys."},"evidence":{"type":"string","maxLength":10000,"description":"Concise tool steps and supporting evidence. Never include credentials."}}}}}}}},"\/questions\/{question}\/verify":{"post":{"operationId":"verifyAnswer","summary":"Equivalent to submitAnswer; consumes an attempt","responses":{"200":{"description":"Successful response","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"description":"Key invalid, expired or revoked"},"403":{"description":"Account or AI module access denied"},"404":{"description":"Question not in this evaluation"},"409":{"description":"Evaluation ended, question disabled or attempt limit reached"},"422":{"description":"Invalid request"},"429":{"description":"Rate limit; respect Retry-After"}},"parameters":[{"name":"question","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Question ID returned by session; not an original training-bank ID."}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["request_id","answer"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Reuse this UUID only for retries of the same answer to this question."},"answer":{"oneOf":[{"type":"string","maxLength":10000},{"type":"array","maxItems":100,"items":{"type":"string","maxLength":200}}],"description":"Single choice\/true-false: option key. Fill blank: exact answer string. Multiple choice: array of option keys."},"evidence":{"type":"string","maxLength":10000,"description":"Concise tool steps and supporting evidence. Never include credentials."}}}}}}}},"\/results":{"get":{"operationId":"getResults","summary":"Read evaluation metrics","responses":{"200":{"description":"Successful response","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"description":"Key invalid, expired or revoked"},"403":{"description":"Account or AI module access denied"},"404":{"description":"Question not in this evaluation"},"409":{"description":"Evaluation ended, question disabled or attempt limit reached"},"422":{"description":"Invalid request"},"429":{"description":"Rate limit; respect Retry-After"}}}},"\/finish":{"post":{"operationId":"finishEvaluation","summary":"Permanently stop submissions and retain results","responses":{"200":{"description":"Successful response","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"description":"Key invalid, expired or revoked"},"403":{"description":"Account or AI module access denied"},"404":{"description":"Question not in this evaluation"},"409":{"description":"Evaluation ended, question disabled or attempt limit reached"},"422":{"description":"Invalid request"},"429":{"description":"Rate limit; respect Retry-After"}}}},"\/questions\/{question}\/artifact":{"get":{"operationId":"downloadArtifact","summary":"Download evidence using the same Bearer Key","parameters":[{"name":"question","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Question ID returned by session; not an original training-bank ID."}],"responses":{"200":{"description":"Private evidence file","content":{"application\/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Key invalid, expired or revoked"},"403":{"description":"Account or AI module access denied"},"404":{"description":"Question not in this evaluation"},"409":{"description":"Evaluation ended, question disabled or attempt limit reached"},"422":{"description":"Invalid request"},"429":{"description":"Rate limit; respect Retry-After"}}}},"\/heartbeat":{"post":{"operationId":"heartbeat","summary":"Keep evaluation connection visible during long analysis; does not consume answer attempts","responses":{"200":{"description":"Evaluation status and server time"},"401":{"description":"Key expired or revoked"},"403":{"description":"AI access denied"},"429":{"description":"Rate limited"}},"description":"\u6bcf 30 \u79d2\u53d1\u9001\u771f\u5b9e\u8fdb\u5c55\uff1b\u9636\u6bb5\u53d8\u5316\u6216\u963b\u585e\u65f6\u7acb\u5373\u4e0a\u62a5\u3002\u4e0d\u6d88\u8017\u7b54\u6848\u6b21\u6570\u3002\u517c\u5bb9\u7a7a JSON\u3002","requestBody":{"required":false,"content":{"application\/json":{"schema":{"type":"object","properties":{"stage":{"type":"string","enum":["preparing","analyzing","submitting","blocked","finishing"]},"question_id":{"type":"string","format":"uuid","description":"\u672c\u8f6e\u9898\u76ee UUID\uff0c\u53ef\u7701\u7565"},"message":{"type":"string","maxLength":120,"description":"\u7b80\u77ed\u8fdb\u5c55\uff0c\u4e0d\u542b\u7b54\u6848\u3001\u51ed\u8bc1\u6216\u79c1\u6709\u8def\u5f84"}}}}}}}},"\/usage":{"post":{"operationId":"recordModelCall","summary":"Report one real model invocation before finishing the run","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["event_id","model","status"],"properties":{"event_id":{"type":"string","format":"uuid","description":"Stable UUID for one actual model invocation. Delivery retries reuse this UUID; new model invocations use a new one."},"question_id":{"type":"string","format":"uuid","nullable":true},"provider":{"type":"string","maxLength":100,"nullable":true},"model":{"type":"string","maxLength":120},"status":{"type":"string","enum":["success","error"]},"input_tokens":{"type":"integer","minimum":0,"maximum":100000000,"nullable":true,"description":"Actual provider-reported count; omit\/null when unknown. Cached input is a subset of input, never added twice."},"output_tokens":{"type":"integer","minimum":0,"maximum":100000000,"nullable":true,"description":"Actual provider-reported count; omit\/null when unknown. Cached input is a subset of input, never added twice."},"cached_input_tokens":{"type":"integer","minimum":0,"maximum":100000000,"nullable":true,"description":"Actual provider-reported count; omit\/null when unknown. Cached input is a subset of input, never added twice."},"duration_ms":{"type":"integer","minimum":0,"maximum":86400000,"nullable":true,"description":"Elapsed time of one model invocation, excluding delivery to Forenbench."}}}}}},"responses":{"200":{"description":"Recorded or idempotently replayed; no answer attempt consumed"},"401":{"description":"Invalid\/rotated\/expired key"},"403":{"description":"AI access withdrawn"},"404":{"description":"Question does not belong to this evaluation"},"409":{"description":"Run ended or event quota exceeded"},"422":{"description":"Invalid counters or same event_id with changed metadata"},"429":{"description":"Respect Retry-After"}}}}},"components":{"securitySchemes":{"evaluationKey":{"type":"http","scheme":"bearer","bearerFormat":"dfb_ followed by 64 lowercase hex characters"}}}}