{"openapi":"3.1.0","info":{"title":"AI3D Benchmark API","version":"1.0.0","description":"Submit checksummed AI-generated 3D deliverables with direct, resumable uploads. Large files never pass through the API server."},"servers":[{"url":"/","description":"Current AI3D Benchmark deployment"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Firebase access token or scoped ai3d_pub_ publisher token."}},"schemas":{"UploadArtifact":{"type":"object","additionalProperties":false,"required":["artifactId","format","mimeType","byteSize","sha256"],"properties":{"artifactId":{"type":"string","format":"uuid"},"format":{"enum":["ply","splat","glb"]},"mimeType":{"enum":["application/octet-stream","application/x-ply","model/gltf-binary"]},"byteSize":{"type":"integer","minimum":1},"sha256":{"type":"string","pattern":"^[a-fA-F0-9]{64}$"}},"oneOf":[{"properties":{"format":{"const":"ply"},"mimeType":{"const":"application/x-ply"}}},{"properties":{"format":{"const":"splat"},"mimeType":{"const":"application/octet-stream"}}},{"properties":{"format":{"const":"glb"},"mimeType":{"const":"model/gltf-binary"}}}]},"DeliverableSubmission":{"type":"object","additionalProperties":false,"required":["benchmarkId","publisher","visibility","generationManifest","artifacts"],"properties":{"benchmarkId":{"type":"string","format":"uuid"},"publisher":{"$ref":"/schemas/publisher/1.0.json"},"visibility":{"enum":["public","unlisted","private"]},"generationManifest":{"$ref":"/schemas/generation-manifest/1.0.json"},"artifacts":{"type":"array","minItems":1,"maxItems":8,"items":{"$ref":"#/components/schemas/UploadArtifact"}}}},"UploadPart":{"type":"object","required":["partNumber","start","end","url"],"properties":{"partNumber":{"type":"integer","minimum":1},"start":{"type":"integer","minimum":0},"end":{"type":"integer","minimum":1},"url":{"type":"string","format":"uri"},"headers":{"type":"object","additionalProperties":{"type":"string"}}}},"ArtifactUploadSession":{"type":"object","required":["artifactId","uploadSessionId","expiresAt","multipart","parts"],"properties":{"artifactId":{"type":"string","format":"uuid"},"uploadSessionId":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"multipart":{"type":"boolean"},"parts":{"type":"array","items":{"$ref":"#/components/schemas/UploadPart"}},"completeUrl":{"type":"string"}}},"ArtifactUploadSessionBatch":{"type":"object","required":["sessions","alreadyCompletedArtifactIds"],"properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/ArtifactUploadSession"}},"alreadyCompletedArtifactIds":{"type":"array","items":{"type":"string","format":"uuid"}}}},"DeliverableSubmissionResponse":{"type":"object","required":["submissionId","resultId","status","statusUrl","uploadSessions"],"properties":{"submissionId":{"type":"string","format":"uuid"},"resultId":{"type":"string","format":"uuid"},"status":{"const":"awaiting-upload"},"statusUrl":{"type":"string"},"uploadSessions":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ArtifactUploadSession"},{"required":["completeUrl"]}]}}}},"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}},"paths":{"/api/v1/deliverable-submissions":{"post":{"operationId":"createDeliverableSubmission","summary":"Create a deliverable submission and signed upload sessions","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Atomically reserved retry key bound to the validated request payload and retained for 24 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverableSubmission"}}}},"responses":{"201":{"description":"Submission created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverableSubmissionResponse"}}}},"400":{"description":"Invalid submission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Invalid or missing credential"},"409":{"description":"Benchmark source is unavailable or inconsistent"},"413":{"description":"An artifact exceeds the configured limit"}}}},"/api/v1/benchmarks/resolve-source":{"post":{"operationId":"resolveSource","summary":"Resolve a benchmark by source image hash"}},"/api/v1/benchmarks":{"post":{"operationId":"createBenchmark","summary":"Create a benchmark","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Atomically reserved retry key bound to the validated request payload and retained for 24 hours."}]}},"/api/v1/benchmarks/{benchmarkId}":{"get":{"operationId":"getBenchmark","summary":"Get a benchmark"}},"/api/v1/benchmarks/{benchmarkId}/source":{"get":{"operationId":"getBenchmarkSource","summary":"Get the benchmark source image"}},"/api/v1/benchmarks/{benchmarkId}/source/upload-session":{"post":{"operationId":"renewBenchmarkSourceUpload","summary":"Renew the owner-only source image upload target","security":[{"bearerAuth":[]}],"parameters":[{"name":"benchmarkId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Atomically reserved retry key bound to the validated request payload and retained for 24 hours."}]}},"/api/v1/benchmarks/{benchmarkId}/results":{"get":{"operationId":"listBenchmarkResults","summary":"List published benchmark results"}},"/api/v1/results":{"post":{"operationId":"createResult","summary":"Create an empty result draft","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Atomically reserved retry key bound to the validated request payload and retained for 24 hours."}]}},"/api/v1/results/{resultId}":{"get":{"operationId":"getResult","summary":"Get a published result","parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/api/v1/results/{resultId}/generation-manifest":{"put":{"operationId":"putGenerationManifest","summary":"Set the generation manifest","security":[{"bearerAuth":[]}],"parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Atomically reserved retry key bound to the validated request payload and retained for 24 hours."}]}},"/api/v1/results/{resultId}/artifacts/upload-session":{"post":{"operationId":"createUploadSession","summary":"Initialize draft uploads or renew one incomplete artifact","security":[{"bearerAuth":[]}],"parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Atomically reserved retry key bound to the validated request payload and retained for 24 hours."}],"description":"Draft initialization accepts 1–8 declarations. Once initialized, declarations are immutable and renewal requires exactly one byte-identical incomplete artifact. Completed artifacts are returned without a new session.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["artifacts"],"properties":{"artifacts":{"type":"array","minItems":1,"maxItems":8,"items":{"$ref":"#/components/schemas/UploadArtifact"}}}}}}},"responses":{"201":{"description":"Sessions created, or the requested artifact was already complete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactUploadSessionBatch"}}}},"400":{"description":"Invalid declaration or multi-artifact renewal; may return SINGLE_ARTIFACT_RENEWAL_REQUIRED"},"409":{"description":"Declaration mismatch or active competing session; may return ARTIFACT_DECLARATION_IMMUTABLE, UPLOAD_SESSION_ACTIVE, or UPLOAD_STATE_CONFLICT"},"413":{"description":"An artifact exceeds the configured limit"}}}},"/api/v1/results/{resultId}/artifacts/{artifactId}/complete":{"post":{"operationId":"completeArtifact","summary":"Verify and complete an artifact upload","security":[{"bearerAuth":[]}],"parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"artifactId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Atomically reserved retry key bound to the validated request payload and retained for 24 hours."}]}},"/api/v1/results/{resultId}/artifacts/{artifactId}/download":{"get":{"operationId":"downloadArtifact","summary":"Create a download URL for a published artifact"}},"/api/v1/results/{resultId}/previews":{"post":{"operationId":"submitPreview","summary":"Set generator preview metadata","security":[{"bearerAuth":[]}],"parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Atomically reserved retry key bound to the validated request payload and retained for 24 hours."}]}},"/api/v1/results/{resultId}/process":{"post":{"operationId":"processResult","summary":"Start validation and processing","security":[{"bearerAuth":[]}],"parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Atomically reserved retry key bound to the validated request payload and retained for 24 hours."}]}},"/api/v1/results/{resultId}/status":{"get":{"operationId":"getResultStatus","summary":"Get submission processing status","parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"bearerAuth":[]}]}},"/api/v1/results/{resultId}/alignments":{"post":{"operationId":"submitAlignment","summary":"Submit an alignment candidate","security":[{"bearerAuth":[]}],"parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Atomically reserved retry key bound to the validated request payload and retained for 24 hours."}]}},"/api/v1/results/{resultId}/canonical-render/upload":{"post":{"operationId":"createCanonicalRenderUpload","summary":"Create a canonical render upload target","security":[{"bearerAuth":[]}],"parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/api/v1/results/{resultId}/canonical-render":{"post":{"operationId":"submitCanonicalRender","summary":"Submit canonical render metadata","security":[{"bearerAuth":[]}],"parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Atomically reserved retry key bound to the validated request payload and retained for 24 hours."}]}},"/api/v1/results/{resultId}/canonical-render/image":{"get":{"operationId":"getCanonicalRender","summary":"Get a published canonical render","parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/api/v1/results/{resultId}/metrics":{"post":{"operationId":"submitMetrics","summary":"Submit metric records","security":[{"bearerAuth":[]}],"parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Atomically reserved retry key bound to the validated request payload and retained for 24 hours."}]}},"/api/v1/results/{resultId}/publish":{"post":{"operationId":"publishResult","summary":"Publish an immutable result","security":[{"bearerAuth":[]}],"parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Atomically reserved retry key bound to the validated request payload and retained for 24 hours."}]}},"/api/v1/results/{resultId}/report":{"get":{"operationId":"getResultReport","summary":"Get the public result report","parameters":[{"name":"resultId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}}}}