{ "components": { "parameters": {}, "schemas": { "Capabilities": { "properties": { "api_version": { "enum": [ "v1" ], "type": "string" }, "file_media_types": { "items": { "type": "string" }, "type": "array" }, "languages": { "items": { "type": "string" }, "type": "array" }, "limits": { "properties": { "maximum_file_bytes": { "exclusiveMinimum": 0, "type": "integer" }, "maximum_files_per_job": { "exclusiveMinimum": 0, "type": "integer" }, "maximum_text_characters": { "exclusiveMinimum": 0, "type": "integer" } }, "required": [ "maximum_file_bytes", "maximum_files_per_job", "maximum_text_characters" ], "type": "object" }, "output_formats": { "items": { "enum": [ "markdown", "jsonl", "zip" ], "type": "string" }, "type": "array" }, "output_profiles": { "items": { "enum": [ "source_summary", "dataset_markdown", "schema_plan", "agent_context", "evaluation_markdown", "raw_source" ], "type": "string" }, "type": "array" }, "plugins": { "items": { "properties": { "canonical_identifier": { "maxLength": 100, "minLength": 3, "type": "string" }, "cost_unit": { "enum": [ "input_bytes", "extracted_characters", "media_minutes", "ocr_pages", "files", "sources" ], "type": "string" }, "id": { "enum": [ "source.webpage", "source.audio_upload", "source.video_upload", "source.ocr", "renderer.dataset_artifacts", "source.repository_archive", "connector.google_drive", "orchestration.batch" ], "type": "string" }, "kind": { "enum": [ "source_adapter", "output_renderer", "connector", "orchestrator" ], "type": "string" }, "limits": { "additionalProperties": { "minimum": 0, "type": "number" }, "type": "object" }, "media_types": { "items": { "type": "string" }, "type": "array" }, "output_formats": { "items": { "enum": [ "markdown", "jsonl", "zip" ], "type": "string" }, "type": "array" }, "quality_threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "status": { "enum": [ "disabled", "beta", "general_availability" ], "type": "string" }, "surfaces": { "items": { "enum": [ "web", "api", "cli", "mcp", "typescript_sdk", "python_sdk", "docs" ], "type": "string" }, "type": "array" }, "use_case": { "maxLength": 300, "minLength": 10, "type": "string" } }, "required": [ "id", "kind", "status", "canonical_identifier", "use_case", "media_types", "output_formats", "cost_unit", "limits", "quality_threshold", "surfaces" ], "type": "object" }, "type": "array" }, "source_types": { "items": { "enum": [ "text", "url", "files" ], "type": "string" }, "type": "array" } }, "required": [ "api_version", "source_types", "file_media_types", "output_profiles", "output_formats", "languages", "plugins", "limits" ], "type": "object" }, "CompleteFileRequest": { "properties": { "sha256": { "pattern": "^[a-f0-9]{64}$/u", "type": "string" }, "size_bytes": { "exclusiveMinimum": 0, "type": "integer" } }, "required": [ "size_bytes", "sha256" ], "type": "object" }, "CreateJobRequest": { "properties": { "output": { "properties": { "format": { "default": "markdown", "enum": [ "markdown", "jsonl", "zip" ], "type": "string" }, "include_raw_source": { "default": false, "type": "boolean" }, "language": { "default": "en", "maxLength": 35, "minLength": 2, "type": "string" }, "profile": { "enum": [ "source_summary", "dataset_markdown", "schema_plan", "agent_context", "evaluation_markdown", "raw_source" ], "type": "string" } }, "required": [ "profile" ], "type": "object" }, "retention": { "default": { "class": "temporary" }, "properties": { "class": { "enum": [ "ephemeral", "temporary", "account" ], "type": "string" } }, "required": [ "class" ], "type": "object" }, "source": { "oneOf": [ { "properties": { "content": { "maxLength": 2000000, "minLength": 1, "type": "string" }, "source_url": { "format": "uri", "type": "string" }, "title": { "maxLength": 300, "minLength": 1, "type": "string" }, "type": { "enum": [ "text" ], "type": "string" } }, "required": [ "type", "content" ], "type": "object" }, { "properties": { "resolver_preferences": { "additionalProperties": false, "properties": { "allow_audio_transcription": { "default": false, "type": "boolean" }, "preferred_language": { "maxLength": 35, "minLength": 2, "type": "string" } }, "type": "object" }, "type": { "enum": [ "url" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "type", "url" ], "type": "object" }, { "properties": { "file_ids": { "items": { "pattern": "^file_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array" }, "type": { "enum": [ "files" ], "type": "string" } }, "required": [ "type", "file_ids" ], "type": "object" } ] } }, "required": [ "source", "output" ], "type": "object" }, "CreateOutputRequest": { "properties": { "output": { "properties": { "format": { "default": "markdown", "enum": [ "markdown", "jsonl", "zip" ], "type": "string" }, "include_raw_source": { "default": false, "type": "boolean" }, "language": { "default": "en", "maxLength": 35, "minLength": 2, "type": "string" }, "profile": { "enum": [ "source_summary", "dataset_markdown", "schema_plan", "agent_context", "evaluation_markdown", "raw_source" ], "type": "string" } }, "required": [ "profile" ], "type": "object" } }, "required": [ "output" ], "type": "object" }, "CreateUploadIntentRequest": { "properties": { "media_type": { "maxLength": 150, "minLength": 3, "type": "string" }, "name": { "maxLength": 255, "minLength": 1, "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$/u", "type": "string" }, "size_bytes": { "exclusiveMinimum": 0, "maximum": 104857600, "type": "integer" } }, "required": [ "name", "media_type", "size_bytes", "sha256" ], "type": "object" }, "File": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "pattern": "^file_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "media_type": { "type": "string" }, "name": { "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$/u", "type": "string" }, "size_bytes": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "pending_upload", "uploaded", "validating", "ready", "rejected", "expired" ], "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "name", "media_type", "size_bytes", "sha256", "status", "warnings", "created_at", "expires_at" ], "type": "object" }, "Job": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "output_ids": { "items": { "pattern": "^out_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "type": "array" }, "progress": { "properties": { "detail": { "type": [ "string", "null" ] }, "percent": { "maximum": 100, "minimum": 0, "type": "number" }, "stage": { "enum": [ "upload_validation", "source_acquisition", "scanning", "extraction", "transcription", "normalization", "chunking", "enrichment", "rendering", "packaging", "finalization", null ], "type": [ "string", "null" ] } }, "required": [ "stage", "percent", "detail" ], "type": "object" }, "source_type": { "enum": [ "text", "url", "files" ], "type": "string" }, "status": { "enum": [ "queued", "processing", "succeeded", "failed", "canceling", "canceled", "expired" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "usage_estimate": { "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "type": "string" }, "currency": { "enum": [ "USD" ], "type": "string" }, "estimated_cost_microusd": { "minimum": 0, "type": "integer" }, "quantities": { "items": { "properties": { "quantity": { "minimum": 0, "type": "number" }, "unit": { "enum": [ "jobs", "uploaded_bytes", "input_bytes", "extracted_pages", "extracted_characters", "media_minutes", "enrichment_tokens", "stored_gigabyte_days", "output_bytes" ], "type": "string" } }, "required": [ "unit", "quantity" ], "type": "object" }, "type": "array" } }, "required": [ "quantities", "estimated_cost_microusd", "currency", "confidence" ], "type": "object" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "status", "progress", "source_type", "output_ids", "warnings", "created_at", "updated_at", "expires_at" ], "type": "object" }, "JobList": { "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "output_ids": { "items": { "pattern": "^out_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "type": "array" }, "progress": { "properties": { "detail": { "type": [ "string", "null" ] }, "percent": { "maximum": 100, "minimum": 0, "type": "number" }, "stage": { "enum": [ "upload_validation", "source_acquisition", "scanning", "extraction", "transcription", "normalization", "chunking", "enrichment", "rendering", "packaging", "finalization", null ], "type": [ "string", "null" ] } }, "required": [ "stage", "percent", "detail" ], "type": "object" }, "source_type": { "enum": [ "text", "url", "files" ], "type": "string" }, "status": { "enum": [ "queued", "processing", "succeeded", "failed", "canceling", "canceled", "expired" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "usage_estimate": { "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "type": "string" }, "currency": { "enum": [ "USD" ], "type": "string" }, "estimated_cost_microusd": { "minimum": 0, "type": "integer" }, "quantities": { "items": { "properties": { "quantity": { "minimum": 0, "type": "number" }, "unit": { "enum": [ "jobs", "uploaded_bytes", "input_bytes", "extracted_pages", "extracted_characters", "media_minutes", "enrichment_tokens", "stored_gigabyte_days", "output_bytes" ], "type": "string" } }, "required": [ "unit", "quantity" ], "type": "object" }, "type": "array" } }, "required": [ "quantities", "estimated_cost_microusd", "currency", "confidence" ], "type": "object" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "status", "progress", "source_type", "output_ids", "warnings", "created_at", "updated_at", "expires_at" ], "type": "object" }, "type": "array" }, "page": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "description": "Opaque pagination cursor", "maxLength": 512, "minLength": 1, "type": [ "string", "null" ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "page" ], "type": "object" }, "Output": { "properties": { "completed_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "format": { "enum": [ "markdown", "jsonl", "zip" ], "type": "string" }, "id": { "pattern": "^out_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "job_id": { "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "language": { "maxLength": 35, "minLength": 2, "type": "string" }, "manifest": { "properties": { "files": { "items": { "properties": { "download_url": { "format": "uri", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "file_id": { "pattern": "^artifact_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "media_type": { "maxLength": 150, "minLength": 3, "type": "string" }, "name": { "maxLength": 255, "minLength": 1, "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$/u", "type": "string" }, "size_bytes": { "minimum": 0, "type": "integer" } }, "required": [ "file_id", "name", "media_type", "size_bytes", "sha256", "expires_at", "download_url" ], "type": "object" }, "minItems": 1, "type": "array" }, "manifest_version": { "enum": [ 1 ], "type": "number" }, "total_size_bytes": { "minimum": 0, "type": "integer" } }, "required": [ "manifest_version", "files", "total_size_bytes" ], "type": [ "object", "null" ] }, "profile": { "enum": [ "source_summary", "dataset_markdown", "schema_plan", "agent_context", "evaluation_markdown", "raw_source" ], "type": "string" }, "status": { "enum": [ "queued", "processing", "succeeded", "failed", "expired" ], "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "job_id", "status", "profile", "format", "language", "warnings", "manifest", "created_at", "completed_at" ], "type": "object" }, "OutputList": { "properties": { "data": { "items": { "properties": { "completed_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "format": { "enum": [ "markdown", "jsonl", "zip" ], "type": "string" }, "id": { "pattern": "^out_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "job_id": { "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "language": { "maxLength": 35, "minLength": 2, "type": "string" }, "manifest": { "properties": { "files": { "items": { "properties": { "download_url": { "format": "uri", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "file_id": { "pattern": "^artifact_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "media_type": { "maxLength": 150, "minLength": 3, "type": "string" }, "name": { "maxLength": 255, "minLength": 1, "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$/u", "type": "string" }, "size_bytes": { "minimum": 0, "type": "integer" } }, "required": [ "file_id", "name", "media_type", "size_bytes", "sha256", "expires_at", "download_url" ], "type": "object" }, "minItems": 1, "type": "array" }, "manifest_version": { "enum": [ 1 ], "type": "number" }, "total_size_bytes": { "minimum": 0, "type": "integer" } }, "required": [ "manifest_version", "files", "total_size_bytes" ], "type": [ "object", "null" ] }, "profile": { "enum": [ "source_summary", "dataset_markdown", "schema_plan", "agent_context", "evaluation_markdown", "raw_source" ], "type": "string" }, "status": { "enum": [ "queued", "processing", "succeeded", "failed", "expired" ], "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "job_id", "status", "profile", "format", "language", "warnings", "manifest", "created_at", "completed_at" ], "type": "object" }, "type": "array" }, "page": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "description": "Opaque pagination cursor", "maxLength": 512, "minLength": 1, "type": [ "string", "null" ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "page" ], "type": "object" }, "ProblemDetails": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" }, "Source": { "oneOf": [ { "properties": { "content": { "maxLength": 2000000, "minLength": 1, "type": "string" }, "source_url": { "format": "uri", "type": "string" }, "title": { "maxLength": 300, "minLength": 1, "type": "string" }, "type": { "enum": [ "text" ], "type": "string" } }, "required": [ "type", "content" ], "type": "object" }, { "properties": { "resolver_preferences": { "additionalProperties": false, "properties": { "allow_audio_transcription": { "default": false, "type": "boolean" }, "preferred_language": { "maxLength": 35, "minLength": 2, "type": "string" } }, "type": "object" }, "type": { "enum": [ "url" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "type", "url" ], "type": "object" }, { "properties": { "file_ids": { "items": { "pattern": "^file_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array" }, "type": { "enum": [ "files" ], "type": "string" } }, "required": [ "type", "file_ids" ], "type": "object" } ] }, "UploadIntent": { "properties": { "expires_at": { "format": "date-time", "type": "string" }, "file_id": { "pattern": "^file_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "upload_headers": { "additionalProperties": { "type": "string" }, "type": "object" }, "upload_method": { "enum": [ "PUT" ], "type": "string" }, "upload_url": { "format": "uri", "type": "string" } }, "required": [ "file_id", "upload_url", "upload_method", "upload_headers", "expires_at" ], "type": "object" }, "Usage": { "properties": { "account_status": { "enum": [ "active", "grace", "suspended", "canceled" ], "type": "string" }, "costs": { "properties": { "billable_cost_microusd": { "minimum": 0, "type": "integer" }, "credits_microusd": { "minimum": 0, "type": "integer" }, "currency": { "enum": [ "USD" ], "type": "string" }, "internal_cost_microusd": { "minimum": 0, "type": "integer" }, "net_due_microusd": { "minimum": 0, "type": "integer" }, "provider_cost_microusd": { "minimum": 0, "type": "integer" }, "refunds_microusd": { "minimum": 0, "type": "integer" } }, "required": [ "currency", "provider_cost_microusd", "internal_cost_microusd", "billable_cost_microusd", "credits_microusd", "refunds_microusd", "net_due_microusd" ], "type": "object" }, "input_bytes": { "minimum": 0, "type": "integer" }, "jobs_created": { "minimum": 0, "type": "integer" }, "limits": { "properties": { "concurrency": { "exclusiveMinimum": 0, "type": "integer" }, "input_bytes": { "minimum": 0, "type": "integer" }, "jobs": { "minimum": 0, "type": "integer" }, "spend_cap_microusd": { "minimum": 0, "type": [ "integer", "null" ] } }, "required": [ "jobs", "input_bytes", "concurrency", "spend_cap_microusd" ], "type": "object" }, "output_bytes": { "minimum": 0, "type": "integer" }, "period_end": { "format": "date-time", "type": "string" }, "period_start": { "format": "date-time", "type": "string" }, "plan": { "enum": [ "metered_beta", "free", "developer", "team", "enterprise" ], "type": "string" }, "units": { "items": { "properties": { "billable": { "minimum": 0, "type": "number" }, "credited": { "minimum": 0, "type": "number" }, "estimated": { "minimum": 0, "type": "number" }, "finalized": { "minimum": 0, "type": "number" }, "pending": { "minimum": 0, "type": "number" }, "unit": { "enum": [ "jobs", "uploaded_bytes", "input_bytes", "extracted_pages", "extracted_characters", "media_minutes", "enrichment_tokens", "stored_gigabyte_days", "output_bytes" ], "type": "string" } }, "required": [ "unit", "estimated", "pending", "finalized", "credited", "billable" ], "type": "object" }, "type": "array" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "period_start", "period_end", "jobs_created", "input_bytes", "output_bytes", "plan", "account_status", "units", "costs", "warnings", "limits" ], "type": "object" }, "WebhookDeliveryList": { "properties": { "data": { "items": { "properties": { "attempts": { "minimum": 0, "type": "integer" }, "completed_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "endpoint_id": { "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "event_id": { "pattern": "^evt_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "event_type": { "enum": [ "job.queued", "job.processing", "job.succeeded", "job.failed", "job.canceled", "output.created", "file.rejected", "quota.warning", "quota.exceeded", "billing.usage_finalized", "billing.invoice_created", "billing.credit_created", "billing.refund_created", "billing.account_updated" ], "type": "string" }, "id": { "pattern": "^whd_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "last_error_code": { "maxLength": 100, "type": [ "string", "null" ] }, "next_attempt_at": { "format": "date-time", "type": [ "string", "null" ] }, "response_preview": { "maxLength": 512, "type": [ "string", "null" ] }, "response_status": { "maximum": 599, "minimum": 100, "type": [ "integer", "null" ] }, "status": { "enum": [ "pending", "delivering", "succeeded", "retrying", "dead_letter" ], "type": "string" } }, "required": [ "id", "event_id", "endpoint_id", "event_type", "status", "attempts", "response_status", "response_preview", "last_error_code", "next_attempt_at", "created_at", "completed_at" ], "type": "object" }, "type": "array" }, "page": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "description": "Opaque pagination cursor", "maxLength": 512, "minLength": 1, "type": [ "string", "null" ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "page" ], "type": "object" }, "WebhookEndpoint": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "description": { "maxLength": 200, "type": "string" }, "events": { "items": { "enum": [ "job.queued", "job.processing", "job.succeeded", "job.failed", "job.canceled", "output.created", "file.rejected", "quota.warning", "quota.exceeded", "billing.usage_finalized", "billing.invoice_created", "billing.credit_created", "billing.refund_created", "billing.account_updated" ], "type": "string" }, "maxItems": 14, "minItems": 1, "type": "array" }, "id": { "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "secret_last_four": { "maxLength": 4, "minLength": 4, "type": "string" }, "status": { "enum": [ "active", "paused" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "id", "url", "description", "events", "status", "secret_last_four", "created_at", "updated_at" ], "type": "object" }, "WebhookEndpointList": { "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "description": { "maxLength": 200, "type": "string" }, "events": { "items": { "enum": [ "job.queued", "job.processing", "job.succeeded", "job.failed", "job.canceled", "output.created", "file.rejected", "quota.warning", "quota.exceeded", "billing.usage_finalized", "billing.invoice_created", "billing.credit_created", "billing.refund_created", "billing.account_updated" ], "type": "string" }, "maxItems": 14, "minItems": 1, "type": "array" }, "id": { "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "secret_last_four": { "maxLength": 4, "minLength": 4, "type": "string" }, "status": { "enum": [ "active", "paused" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "id", "url", "description", "events", "status", "secret_last_four", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "page": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "description": "Opaque pagination cursor", "maxLength": 512, "minLength": 1, "type": [ "string", "null" ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "page" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "bearerFormat": "API key or OAuth access token", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Stable v1 contract for source-to-agent-ready content workflows.", "title": "GetMD API", "version": "1.3.0" }, "openapi": "3.1.0", "paths": { "/v1/capabilities": { "get": { "operationId": "getCapabilities", "responses": { "200": { "content": { "application/json": { "example": { "api_version": "v1", "file_media_types": [ "text/plain", "text/markdown", "application/pdf" ], "languages": [ "en", "hi" ], "limits": { "maximum_file_bytes": 104857600, "maximum_files_per_job": 20, "maximum_text_characters": 2000000 }, "output_formats": [ "markdown" ], "output_profiles": [ "source_summary", "agent_context" ], "plugins": [ { "canonical_identifier": "webpage.v1", "cost_unit": "extracted_characters", "id": "source.webpage", "kind": "source_adapter", "limits": { "maximum_bytes": 5000000, "maximum_redirects": 5, "timeout_seconds": 20 }, "media_types": [ "text/html", "application/xhtml+xml" ], "output_formats": [], "quality_threshold": 0.8, "status": "disabled", "surfaces": [ "web", "api", "cli", "mcp", "typescript_sdk", "python_sdk", "docs" ], "use_case": "Extract structured, attributable content from one public HTTPS webpage." }, { "canonical_identifier": "uploaded_audio.v1", "cost_unit": "media_minutes", "id": "source.audio_upload", "kind": "source_adapter", "limits": { "maximum_bytes": 524288000, "maximum_duration_seconds": 14400, "temporary_disk_bytes": 1073741824 }, "media_types": [ "audio/mpeg", "audio/mp4", "audio/wav", "audio/webm", "audio/ogg" ], "output_formats": [], "quality_threshold": 0.82, "status": "disabled", "surfaces": [ "web", "api", "cli", "mcp", "typescript_sdk", "python_sdk", "docs" ], "use_case": "Transcribe bounded uploaded audio while preserving timestamps and confidence." }, { "canonical_identifier": "uploaded_video.v1", "cost_unit": "media_minutes", "id": "source.video_upload", "kind": "source_adapter", "limits": { "maximum_bytes": 1073741824, "maximum_duration_seconds": 14400, "maximum_height": 2160, "maximum_width": 3840, "temporary_disk_bytes": 2147483648 }, "media_types": [ "video/mp4", "video/webm", "video/quicktime" ], "output_formats": [], "quality_threshold": 0.82, "status": "disabled", "surfaces": [ "web", "api", "cli", "mcp", "typescript_sdk", "python_sdk", "docs" ], "use_case": "Extract a bounded audio track from uploaded video for attributable transcription." }, { "canonical_identifier": "ocr_document.v1", "cost_unit": "ocr_pages", "id": "source.ocr", "kind": "source_adapter", "limits": { "maximum_bytes": 104857600, "maximum_pages": 500, "minimum_confidence": 0.7 }, "media_types": [ "application/pdf", "image/jpeg", "image/png", "image/tiff" ], "output_formats": [], "quality_threshold": 0.7, "status": "disabled", "surfaces": [ "web", "api", "cli", "mcp", "typescript_sdk", "python_sdk", "docs" ], "use_case": "Recover text from image-only documents and images with page coordinates and confidence warnings." }, { "canonical_identifier": "dataset_artifacts.v1", "cost_unit": "extracted_characters", "id": "renderer.dataset_artifacts", "kind": "output_renderer", "limits": { "maximum_archive_bytes": 536870912, "maximum_records": 100000 }, "media_types": [], "output_formats": [ "jsonl", "zip" ], "quality_threshold": 0.9, "status": "disabled", "surfaces": [ "web", "api", "cli", "mcp", "typescript_sdk", "python_sdk", "docs" ], "use_case": "Render checksummed JSONL, metadata, provenance, evaluation, and ZIP dataset artifacts." }, { "canonical_identifier": "repository_archive.v1", "cost_unit": "files", "id": "source.repository_archive", "kind": "source_adapter", "limits": { "maximum_bytes": 524288000, "maximum_file_bytes": 2000000, "maximum_files": 20000 }, "media_types": [ "application/zip", "application/x-tar", "application/gzip" ], "output_formats": [], "quality_threshold": 0.85, "status": "disabled", "surfaces": [ "web", "api", "cli", "mcp", "typescript_sdk", "python_sdk", "docs" ], "use_case": "Extract a bounded source snapshot while excluding secrets, binaries, ignored paths, and generated files." }, { "canonical_identifier": "google_drive_file.v1", "cost_unit": "input_bytes", "id": "connector.google_drive", "kind": "connector", "limits": { "maximum_bytes": 524288000, "maximum_files": 20 }, "media_types": [], "output_formats": [], "quality_threshold": 0.85, "status": "disabled", "surfaces": [ "web", "api", "cli", "mcp", "typescript_sdk", "python_sdk", "docs" ], "use_case": "Import explicitly selected Google Drive files with minimum read-only scopes and revocation handling." }, { "canonical_identifier": "batch_job.v1", "cost_unit": "sources", "id": "orchestration.batch", "kind": "orchestrator", "limits": { "maximum_concurrency": 10, "maximum_sources": 100 }, "media_types": [], "output_formats": [ "markdown", "jsonl", "zip" ], "quality_threshold": 0.9, "status": "disabled", "surfaces": [ "web", "api", "cli", "mcp", "typescript_sdk", "python_sdk", "docs" ], "use_case": "Create a bounded collection of child jobs with aggregate progress and checksummed manifests." } ], "source_types": [ "text", "url", "files" ] }, "schema": { "properties": { "api_version": { "enum": [ "v1" ], "type": "string" }, "file_media_types": { "items": { "type": "string" }, "type": "array" }, "languages": { "items": { "type": "string" }, "type": "array" }, "limits": { "properties": { "maximum_file_bytes": { "exclusiveMinimum": 0, "type": "integer" }, "maximum_files_per_job": { "exclusiveMinimum": 0, "type": "integer" }, "maximum_text_characters": { "exclusiveMinimum": 0, "type": "integer" } }, "required": [ "maximum_file_bytes", "maximum_files_per_job", "maximum_text_characters" ], "type": "object" }, "output_formats": { "items": { "enum": [ "markdown", "jsonl", "zip" ], "type": "string" }, "type": "array" }, "output_profiles": { "items": { "enum": [ "source_summary", "dataset_markdown", "schema_plan", "agent_context", "evaluation_markdown", "raw_source" ], "type": "string" }, "type": "array" }, "plugins": { "items": { "properties": { "canonical_identifier": { "maxLength": 100, "minLength": 3, "type": "string" }, "cost_unit": { "enum": [ "input_bytes", "extracted_characters", "media_minutes", "ocr_pages", "files", "sources" ], "type": "string" }, "id": { "enum": [ "source.webpage", "source.audio_upload", "source.video_upload", "source.ocr", "renderer.dataset_artifacts", "source.repository_archive", "connector.google_drive", "orchestration.batch" ], "type": "string" }, "kind": { "enum": [ "source_adapter", "output_renderer", "connector", "orchestrator" ], "type": "string" }, "limits": { "additionalProperties": { "minimum": 0, "type": "number" }, "type": "object" }, "media_types": { "items": { "type": "string" }, "type": "array" }, "output_formats": { "items": { "enum": [ "markdown", "jsonl", "zip" ], "type": "string" }, "type": "array" }, "quality_threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "status": { "enum": [ "disabled", "beta", "general_availability" ], "type": "string" }, "surfaces": { "items": { "enum": [ "web", "api", "cli", "mcp", "typescript_sdk", "python_sdk", "docs" ], "type": "string" }, "type": "array" }, "use_case": { "maxLength": 300, "minLength": 10, "type": "string" } }, "required": [ "id", "kind", "status", "canonical_identifier", "use_case", "media_types", "output_formats", "cost_unit", "limits", "quality_threshold", "surfaces" ], "type": "object" }, "type": "array" }, "source_types": { "items": { "enum": [ "text", "url", "files" ], "type": "string" }, "type": "array" } }, "required": [ "api_version", "source_types", "file_media_types", "output_profiles", "output_formats", "languages", "plugins", "limits" ], "type": "object" } } }, "description": "Current v1 capabilities", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "security": [], "summary": "Describe supported sources, outputs, languages, and limits", "tags": [ "Capabilities" ] } }, "/v1/files/{file_id}": { "delete": { "operationId": "deleteFile", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "example": "file_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^file_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "responses": { "204": { "description": "File deleted", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "example": { "code": "idempotency_conflict", "detail": "The idempotency key was already used with a different request.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 409, "title": "Idempotency conflict", "type": "https://getmd.xyz/problems/idempotency_conflict" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Delete an account-owned file", "tags": [ "Files" ] }, "get": { "operationId": "getFile", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "example": "file_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^file_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "created_at": "2026-08-23T12:00:00.000Z", "expires_at": "2026-08-24T12:00:00.000Z", "id": "file_01K3M8H6DN5ZG2Q8FJTX", "media_type": "application/pdf", "name": "source.pdf", "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "size_bytes": 56000, "status": "ready", "warnings": [] }, "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "pattern": "^file_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "media_type": { "type": "string" }, "name": { "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$/u", "type": "string" }, "size_bytes": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "pending_upload", "uploaded", "validating", "ready", "rejected", "expired" ], "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "name", "media_type", "size_bytes", "sha256", "status", "warnings", "created_at", "expires_at" ], "type": "object" } } }, "description": "File", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Get an account-owned file", "tags": [ "Files" ] } }, "/v1/files/{file_id}/complete": { "post": { "operationId": "completeFileUpload", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "example": "file_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^file_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "size_bytes": 56000 }, "schema": { "properties": { "sha256": { "pattern": "^[a-f0-9]{64}$/u", "type": "string" }, "size_bytes": { "exclusiveMinimum": 0, "type": "integer" } }, "required": [ "size_bytes", "sha256" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "created_at": "2026-08-23T12:00:00.000Z", "expires_at": "2026-08-24T12:00:00.000Z", "id": "file_01K3M8H6DN5ZG2Q8FJTX", "media_type": "application/pdf", "name": "source.pdf", "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "size_bytes": 56000, "status": "ready", "warnings": [] }, "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "pattern": "^file_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "media_type": { "type": "string" }, "name": { "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$/u", "type": "string" }, "size_bytes": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "pending_upload", "uploaded", "validating", "ready", "rejected", "expired" ], "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "name", "media_type", "size_bytes", "sha256", "status", "warnings", "created_at", "expires_at" ], "type": "object" } } }, "description": "File validation queued", "headers": { "Location": { "description": "Canonical URL of the durable resource", "schema": { "format": "uri", "type": "string" } }, "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "example": { "code": "idempotency_conflict", "detail": "The idempotency key was already used with a different request.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 409, "title": "Idempotency conflict", "type": "https://getmd.xyz/problems/idempotency_conflict" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "example": { "code": "validation_failed", "detail": "One or more request fields are invalid.", "field_errors": [ { "code": "invalid_url", "detail": "URL must use HTTPS.", "field": "source.url" } ], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 422, "title": "Validation failed", "type": "https://getmd.xyz/problems/validation_failed" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Confirm a direct upload and start validation", "tags": [ "Files" ] } }, "/v1/jobs": { "get": { "operationId": "listJobs", "parameters": [ { "description": "Opaque pagination cursor", "in": "query", "name": "cursor", "required": false, "schema": { "description": "Opaque pagination cursor", "maxLength": 512, "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "created_at": "2026-08-23T12:00:00.000Z", "expires_at": "2026-08-24T12:00:00.000Z", "id": "job_01K3M8H6DN5ZG2Q8FJTX", "output_ids": [ "out_01K3M8H6DN5ZG2Q8FJTX" ], "progress": { "detail": "Extracting page 3 of 8", "percent": 45, "stage": "extraction" }, "source_type": "url", "status": "processing", "updated_at": "2026-08-23T12:00:00.000Z", "warnings": [] } ], "page": { "has_more": false, "next_cursor": null } }, "schema": { "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "output_ids": { "items": { "pattern": "^out_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "type": "array" }, "progress": { "properties": { "detail": { "type": [ "string", "null" ] }, "percent": { "maximum": 100, "minimum": 0, "type": "number" }, "stage": { "enum": [ "upload_validation", "source_acquisition", "scanning", "extraction", "transcription", "normalization", "chunking", "enrichment", "rendering", "packaging", "finalization", null ], "type": [ "string", "null" ] } }, "required": [ "stage", "percent", "detail" ], "type": "object" }, "source_type": { "enum": [ "text", "url", "files" ], "type": "string" }, "status": { "enum": [ "queued", "processing", "succeeded", "failed", "canceling", "canceled", "expired" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "usage_estimate": { "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "type": "string" }, "currency": { "enum": [ "USD" ], "type": "string" }, "estimated_cost_microusd": { "minimum": 0, "type": "integer" }, "quantities": { "items": { "properties": { "quantity": { "minimum": 0, "type": "number" }, "unit": { "enum": [ "jobs", "uploaded_bytes", "input_bytes", "extracted_pages", "extracted_characters", "media_minutes", "enrichment_tokens", "stored_gigabyte_days", "output_bytes" ], "type": "string" } }, "required": [ "unit", "quantity" ], "type": "object" }, "type": "array" } }, "required": [ "quantities", "estimated_cost_microusd", "currency", "confidence" ], "type": "object" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "status", "progress", "source_type", "output_ids", "warnings", "created_at", "updated_at", "expires_at" ], "type": "object" }, "type": "array" }, "page": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "description": "Opaque pagination cursor", "maxLength": 512, "minLength": 1, "type": [ "string", "null" ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "page" ], "type": "object" } } }, "description": "Job page", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "List jobs using cursor pagination", "tags": [ "Jobs" ] }, "post": { "operationId": "createJob", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "example": "idem_01K3M8H6DN5ZG2Q8FJTX", "maxLength": 255, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "output": { "format": "markdown", "include_raw_source": false, "language": "en", "profile": "agent_context" }, "retention": { "class": "temporary" }, "source": { "type": "url", "url": "https://www.youtube.com/watch?v=example" } }, "schema": { "properties": { "output": { "properties": { "format": { "default": "markdown", "enum": [ "markdown", "jsonl", "zip" ], "type": "string" }, "include_raw_source": { "default": false, "type": "boolean" }, "language": { "default": "en", "maxLength": 35, "minLength": 2, "type": "string" }, "profile": { "enum": [ "source_summary", "dataset_markdown", "schema_plan", "agent_context", "evaluation_markdown", "raw_source" ], "type": "string" } }, "required": [ "profile" ], "type": "object" }, "retention": { "default": { "class": "temporary" }, "properties": { "class": { "enum": [ "ephemeral", "temporary", "account" ], "type": "string" } }, "required": [ "class" ], "type": "object" }, "source": { "oneOf": [ { "properties": { "content": { "maxLength": 2000000, "minLength": 1, "type": "string" }, "source_url": { "format": "uri", "type": "string" }, "title": { "maxLength": 300, "minLength": 1, "type": "string" }, "type": { "enum": [ "text" ], "type": "string" } }, "required": [ "type", "content" ], "type": "object" }, { "properties": { "resolver_preferences": { "additionalProperties": false, "properties": { "allow_audio_transcription": { "default": false, "type": "boolean" }, "preferred_language": { "maxLength": 35, "minLength": 2, "type": "string" } }, "type": "object" }, "type": { "enum": [ "url" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "type", "url" ], "type": "object" }, { "properties": { "file_ids": { "items": { "pattern": "^file_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array" }, "type": { "enum": [ "files" ], "type": "string" } }, "required": [ "type", "file_ids" ], "type": "object" } ] } }, "required": [ "source", "output" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "created_at": "2026-08-23T12:00:00.000Z", "expires_at": "2026-08-24T12:00:00.000Z", "id": "job_01K3M8H6DN5ZG2Q8FJTX", "output_ids": [ "out_01K3M8H6DN5ZG2Q8FJTX" ], "progress": { "detail": "Extracting page 3 of 8", "percent": 45, "stage": "extraction" }, "source_type": "url", "status": "processing", "updated_at": "2026-08-23T12:00:00.000Z", "warnings": [] }, "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "output_ids": { "items": { "pattern": "^out_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "type": "array" }, "progress": { "properties": { "detail": { "type": [ "string", "null" ] }, "percent": { "maximum": 100, "minimum": 0, "type": "number" }, "stage": { "enum": [ "upload_validation", "source_acquisition", "scanning", "extraction", "transcription", "normalization", "chunking", "enrichment", "rendering", "packaging", "finalization", null ], "type": [ "string", "null" ] } }, "required": [ "stage", "percent", "detail" ], "type": "object" }, "source_type": { "enum": [ "text", "url", "files" ], "type": "string" }, "status": { "enum": [ "queued", "processing", "succeeded", "failed", "canceling", "canceled", "expired" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "usage_estimate": { "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "type": "string" }, "currency": { "enum": [ "USD" ], "type": "string" }, "estimated_cost_microusd": { "minimum": 0, "type": "integer" }, "quantities": { "items": { "properties": { "quantity": { "minimum": 0, "type": "number" }, "unit": { "enum": [ "jobs", "uploaded_bytes", "input_bytes", "extracted_pages", "extracted_characters", "media_minutes", "enrichment_tokens", "stored_gigabyte_days", "output_bytes" ], "type": "string" } }, "required": [ "unit", "quantity" ], "type": "object" }, "type": "array" } }, "required": [ "quantities", "estimated_cost_microusd", "currency", "confidence" ], "type": "object" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "status", "progress", "source_type", "output_ids", "warnings", "created_at", "updated_at", "expires_at" ], "type": "object" } } }, "description": "Job durably queued", "headers": { "Location": { "description": "Canonical URL of the durable resource", "schema": { "format": "uri", "type": "string" } }, "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "example": { "code": "idempotency_conflict", "detail": "The idempotency key was already used with a different request.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 409, "title": "Idempotency conflict", "type": "https://getmd.xyz/problems/idempotency_conflict" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "example": { "code": "validation_failed", "detail": "One or more request fields are invalid.", "field_errors": [ { "code": "invalid_url", "detail": "URL must use HTTPS.", "field": "source.url" } ], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 422, "title": "Validation failed", "type": "https://getmd.xyz/problems/validation_failed" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Create a durable conversion job", "tags": [ "Jobs" ] } }, "/v1/jobs/{job_id}": { "delete": { "operationId": "deleteJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "example": "job_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "responses": { "204": { "description": "Job deleted", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "example": { "code": "idempotency_conflict", "detail": "The idempotency key was already used with a different request.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 409, "title": "Idempotency conflict", "type": "https://getmd.xyz/problems/idempotency_conflict" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Delete a terminal job and its outputs", "tags": [ "Jobs" ] }, "get": { "operationId": "getJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "example": "job_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "created_at": "2026-08-23T12:00:00.000Z", "expires_at": "2026-08-24T12:00:00.000Z", "id": "job_01K3M8H6DN5ZG2Q8FJTX", "output_ids": [ "out_01K3M8H6DN5ZG2Q8FJTX" ], "progress": { "detail": "Extracting page 3 of 8", "percent": 45, "stage": "extraction" }, "source_type": "url", "status": "processing", "updated_at": "2026-08-23T12:00:00.000Z", "warnings": [] }, "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "output_ids": { "items": { "pattern": "^out_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "type": "array" }, "progress": { "properties": { "detail": { "type": [ "string", "null" ] }, "percent": { "maximum": 100, "minimum": 0, "type": "number" }, "stage": { "enum": [ "upload_validation", "source_acquisition", "scanning", "extraction", "transcription", "normalization", "chunking", "enrichment", "rendering", "packaging", "finalization", null ], "type": [ "string", "null" ] } }, "required": [ "stage", "percent", "detail" ], "type": "object" }, "source_type": { "enum": [ "text", "url", "files" ], "type": "string" }, "status": { "enum": [ "queued", "processing", "succeeded", "failed", "canceling", "canceled", "expired" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "usage_estimate": { "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "type": "string" }, "currency": { "enum": [ "USD" ], "type": "string" }, "estimated_cost_microusd": { "minimum": 0, "type": "integer" }, "quantities": { "items": { "properties": { "quantity": { "minimum": 0, "type": "number" }, "unit": { "enum": [ "jobs", "uploaded_bytes", "input_bytes", "extracted_pages", "extracted_characters", "media_minutes", "enrichment_tokens", "stored_gigabyte_days", "output_bytes" ], "type": "string" } }, "required": [ "unit", "quantity" ], "type": "object" }, "type": "array" } }, "required": [ "quantities", "estimated_cost_microusd", "currency", "confidence" ], "type": "object" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "status", "progress", "source_type", "output_ids", "warnings", "created_at", "updated_at", "expires_at" ], "type": "object" } } }, "description": "Job", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Get job status and progress", "tags": [ "Jobs" ] } }, "/v1/jobs/{job_id}/cancel": { "post": { "operationId": "cancelJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "example": "job_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "example": { "created_at": "2026-08-23T12:00:00.000Z", "expires_at": "2026-08-24T12:00:00.000Z", "id": "job_01K3M8H6DN5ZG2Q8FJTX", "output_ids": [ "out_01K3M8H6DN5ZG2Q8FJTX" ], "progress": { "detail": "Extracting page 3 of 8", "percent": 45, "stage": "extraction" }, "source_type": "url", "status": "canceling", "updated_at": "2026-08-23T12:00:00.000Z", "warnings": [] }, "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "output_ids": { "items": { "pattern": "^out_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "type": "array" }, "progress": { "properties": { "detail": { "type": [ "string", "null" ] }, "percent": { "maximum": 100, "minimum": 0, "type": "number" }, "stage": { "enum": [ "upload_validation", "source_acquisition", "scanning", "extraction", "transcription", "normalization", "chunking", "enrichment", "rendering", "packaging", "finalization", null ], "type": [ "string", "null" ] } }, "required": [ "stage", "percent", "detail" ], "type": "object" }, "source_type": { "enum": [ "text", "url", "files" ], "type": "string" }, "status": { "enum": [ "queued", "processing", "succeeded", "failed", "canceling", "canceled", "expired" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "usage_estimate": { "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "type": "string" }, "currency": { "enum": [ "USD" ], "type": "string" }, "estimated_cost_microusd": { "minimum": 0, "type": "integer" }, "quantities": { "items": { "properties": { "quantity": { "minimum": 0, "type": "number" }, "unit": { "enum": [ "jobs", "uploaded_bytes", "input_bytes", "extracted_pages", "extracted_characters", "media_minutes", "enrichment_tokens", "stored_gigabyte_days", "output_bytes" ], "type": "string" } }, "required": [ "unit", "quantity" ], "type": "object" }, "type": "array" } }, "required": [ "quantities", "estimated_cost_microusd", "currency", "confidence" ], "type": "object" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "status", "progress", "source_type", "output_ids", "warnings", "created_at", "updated_at", "expires_at" ], "type": "object" } } }, "description": "Cancellation requested", "headers": { "Location": { "description": "Canonical URL of the durable resource", "schema": { "format": "uri", "type": "string" } }, "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "example": { "code": "idempotency_conflict", "detail": "The idempotency key was already used with a different request.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 409, "title": "Idempotency conflict", "type": "https://getmd.xyz/problems/idempotency_conflict" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Request cooperative job cancellation", "tags": [ "Jobs" ] } }, "/v1/jobs/{job_id}/outputs": { "get": { "operationId": "listJobOutputs", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "example": "job_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" } }, { "description": "Opaque pagination cursor", "in": "query", "name": "cursor", "required": false, "schema": { "description": "Opaque pagination cursor", "maxLength": 512, "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "completed_at": "2026-08-23T12:00:00.000Z", "created_at": "2026-08-23T12:00:00.000Z", "format": "markdown", "id": "out_01K3M8H6DN5ZG2Q8FJTX", "job_id": "job_01K3M8H6DN5ZG2Q8FJTX", "language": "en", "manifest": { "files": [ { "download_url": "https://api.getmd.xyz/v1/outputs/out_01K3M8H6DN5ZG2Q8FJTX/content", "expires_at": "2026-08-24T12:00:00.000Z", "file_id": "artifact_01K3M8H6DN5ZG2Q8FJTX", "media_type": "text/markdown", "name": "agent-context.md", "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "size_bytes": 4096 } ], "manifest_version": 1, "total_size_bytes": 4096 }, "profile": "agent_context", "status": "succeeded", "warnings": [] } ], "page": { "has_more": false, "next_cursor": null } }, "schema": { "properties": { "data": { "items": { "properties": { "completed_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "format": { "enum": [ "markdown", "jsonl", "zip" ], "type": "string" }, "id": { "pattern": "^out_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "job_id": { "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "language": { "maxLength": 35, "minLength": 2, "type": "string" }, "manifest": { "properties": { "files": { "items": { "properties": { "download_url": { "format": "uri", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "file_id": { "pattern": "^artifact_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "media_type": { "maxLength": 150, "minLength": 3, "type": "string" }, "name": { "maxLength": 255, "minLength": 1, "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$/u", "type": "string" }, "size_bytes": { "minimum": 0, "type": "integer" } }, "required": [ "file_id", "name", "media_type", "size_bytes", "sha256", "expires_at", "download_url" ], "type": "object" }, "minItems": 1, "type": "array" }, "manifest_version": { "enum": [ 1 ], "type": "number" }, "total_size_bytes": { "minimum": 0, "type": "integer" } }, "required": [ "manifest_version", "files", "total_size_bytes" ], "type": [ "object", "null" ] }, "profile": { "enum": [ "source_summary", "dataset_markdown", "schema_plan", "agent_context", "evaluation_markdown", "raw_source" ], "type": "string" }, "status": { "enum": [ "queued", "processing", "succeeded", "failed", "expired" ], "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "job_id", "status", "profile", "format", "language", "warnings", "manifest", "created_at", "completed_at" ], "type": "object" }, "type": "array" }, "page": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "description": "Opaque pagination cursor", "maxLength": 512, "minLength": 1, "type": [ "string", "null" ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "page" ], "type": "object" } } }, "description": "Output page", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "List outputs for a job", "tags": [ "Outputs" ] }, "post": { "operationId": "createJobOutput", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "example": "job_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "example": "idem_01K3M8H6DN5ZG2Q8FJTX", "maxLength": 255, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "output": { "format": "markdown", "include_raw_source": false, "language": "en", "profile": "source_summary" } }, "schema": { "properties": { "output": { "properties": { "format": { "default": "markdown", "enum": [ "markdown", "jsonl", "zip" ], "type": "string" }, "include_raw_source": { "default": false, "type": "boolean" }, "language": { "default": "en", "maxLength": 35, "minLength": 2, "type": "string" }, "profile": { "enum": [ "source_summary", "dataset_markdown", "schema_plan", "agent_context", "evaluation_markdown", "raw_source" ], "type": "string" } }, "required": [ "profile" ], "type": "object" } }, "required": [ "output" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "completed_at": "2026-08-23T12:00:00.000Z", "created_at": "2026-08-23T12:00:00.000Z", "format": "markdown", "id": "out_01K3M8H6DN5ZG2Q8FJTX", "job_id": "job_01K3M8H6DN5ZG2Q8FJTX", "language": "en", "manifest": { "files": [ { "download_url": "https://api.getmd.xyz/v1/outputs/out_01K3M8H6DN5ZG2Q8FJTX/content", "expires_at": "2026-08-24T12:00:00.000Z", "file_id": "artifact_01K3M8H6DN5ZG2Q8FJTX", "media_type": "text/markdown", "name": "agent-context.md", "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "size_bytes": 4096 } ], "manifest_version": 1, "total_size_bytes": 4096 }, "profile": "agent_context", "status": "succeeded", "warnings": [] }, "schema": { "properties": { "completed_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "format": { "enum": [ "markdown", "jsonl", "zip" ], "type": "string" }, "id": { "pattern": "^out_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "job_id": { "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "language": { "maxLength": 35, "minLength": 2, "type": "string" }, "manifest": { "properties": { "files": { "items": { "properties": { "download_url": { "format": "uri", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "file_id": { "pattern": "^artifact_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "media_type": { "maxLength": 150, "minLength": 3, "type": "string" }, "name": { "maxLength": 255, "minLength": 1, "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$/u", "type": "string" }, "size_bytes": { "minimum": 0, "type": "integer" } }, "required": [ "file_id", "name", "media_type", "size_bytes", "sha256", "expires_at", "download_url" ], "type": "object" }, "minItems": 1, "type": "array" }, "manifest_version": { "enum": [ 1 ], "type": "number" }, "total_size_bytes": { "minimum": 0, "type": "integer" } }, "required": [ "manifest_version", "files", "total_size_bytes" ], "type": [ "object", "null" ] }, "profile": { "enum": [ "source_summary", "dataset_markdown", "schema_plan", "agent_context", "evaluation_markdown", "raw_source" ], "type": "string" }, "status": { "enum": [ "queued", "processing", "succeeded", "failed", "expired" ], "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "job_id", "status", "profile", "format", "language", "warnings", "manifest", "created_at", "completed_at" ], "type": "object" } } }, "description": "Output durably queued", "headers": { "Location": { "description": "Canonical URL of the durable resource", "schema": { "format": "uri", "type": "string" } }, "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "example": { "code": "idempotency_conflict", "detail": "The idempotency key was already used with a different request.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 409, "title": "Idempotency conflict", "type": "https://getmd.xyz/problems/idempotency_conflict" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "example": { "code": "validation_failed", "detail": "One or more request fields are invalid.", "field_errors": [ { "code": "invalid_url", "detail": "URL must use HTTPS.", "field": "source.url" } ], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 422, "title": "Validation failed", "type": "https://getmd.xyz/problems/validation_failed" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Create another output from an existing job", "tags": [ "Outputs" ] } }, "/v1/outputs/{output_id}": { "get": { "operationId": "getOutput", "parameters": [ { "in": "path", "name": "output_id", "required": true, "schema": { "example": "out_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^out_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "completed_at": "2026-08-23T12:00:00.000Z", "created_at": "2026-08-23T12:00:00.000Z", "format": "markdown", "id": "out_01K3M8H6DN5ZG2Q8FJTX", "job_id": "job_01K3M8H6DN5ZG2Q8FJTX", "language": "en", "manifest": { "files": [ { "download_url": "https://api.getmd.xyz/v1/outputs/out_01K3M8H6DN5ZG2Q8FJTX/content", "expires_at": "2026-08-24T12:00:00.000Z", "file_id": "artifact_01K3M8H6DN5ZG2Q8FJTX", "media_type": "text/markdown", "name": "agent-context.md", "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "size_bytes": 4096 } ], "manifest_version": 1, "total_size_bytes": 4096 }, "profile": "agent_context", "status": "succeeded", "warnings": [] }, "schema": { "properties": { "completed_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "format": { "enum": [ "markdown", "jsonl", "zip" ], "type": "string" }, "id": { "pattern": "^out_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "job_id": { "pattern": "^job_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "language": { "maxLength": 35, "minLength": 2, "type": "string" }, "manifest": { "properties": { "files": { "items": { "properties": { "download_url": { "format": "uri", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "file_id": { "pattern": "^artifact_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "media_type": { "maxLength": 150, "minLength": 3, "type": "string" }, "name": { "maxLength": 255, "minLength": 1, "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$/u", "type": "string" }, "size_bytes": { "minimum": 0, "type": "integer" } }, "required": [ "file_id", "name", "media_type", "size_bytes", "sha256", "expires_at", "download_url" ], "type": "object" }, "minItems": 1, "type": "array" }, "manifest_version": { "enum": [ 1 ], "type": "number" }, "total_size_bytes": { "minimum": 0, "type": "integer" } }, "required": [ "manifest_version", "files", "total_size_bytes" ], "type": [ "object", "null" ] }, "profile": { "enum": [ "source_summary", "dataset_markdown", "schema_plan", "agent_context", "evaluation_markdown", "raw_source" ], "type": "string" }, "status": { "enum": [ "queued", "processing", "succeeded", "failed", "expired" ], "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "job_id", "status", "profile", "format", "language", "warnings", "manifest", "created_at", "completed_at" ], "type": "object" } } }, "description": "Output", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Get output metadata and artifact manifest", "tags": [ "Outputs" ] } }, "/v1/outputs/{output_id}/content": { "get": { "operationId": "getOutputContent", "parameters": [ { "in": "path", "name": "output_id", "required": true, "schema": { "example": "out_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^out_[A-Za-z0-9_-]{12,}$/u", "type": "string" } }, { "description": "Opaque pagination cursor", "in": "query", "name": "cursor", "required": false, "schema": { "description": "Opaque pagination cursor", "maxLength": 512, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "text/markdown": { "example": "# Agent Context\n\nGrounded source content.", "schema": { "type": "string" } } }, "description": "Markdown content or a bounded content page", "headers": { "X-Next-Cursor": { "description": "Opaque next cursor", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Read output content using an optional opaque cursor", "tags": [ "Outputs" ] } }, "/v1/upload-intents": { "post": { "operationId": "createUploadIntent", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "example": "idem_01K3M8H6DN5ZG2Q8FJTX", "maxLength": 255, "minLength": 8, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "media_type": "application/pdf", "name": "source.pdf", "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "size_bytes": 56000 }, "schema": { "properties": { "media_type": { "maxLength": 150, "minLength": 3, "type": "string" }, "name": { "maxLength": 255, "minLength": 1, "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$/u", "type": "string" }, "size_bytes": { "exclusiveMinimum": 0, "maximum": 104857600, "type": "integer" } }, "required": [ "name", "media_type", "size_bytes", "sha256" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "expires_at": "2026-08-24T12:00:00.000Z", "file_id": "file_01K3M8H6DN5ZG2Q8FJTX", "upload_headers": { "content-type": "application/pdf" }, "upload_method": "PUT", "upload_url": "https://uploads.getmd.xyz/file_01K3M8H6DN5ZG2Q8FJTX" }, "schema": { "properties": { "expires_at": { "format": "date-time", "type": "string" }, "file_id": { "pattern": "^file_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "upload_headers": { "additionalProperties": { "type": "string" }, "type": "object" }, "upload_method": { "enum": [ "PUT" ], "type": "string" }, "upload_url": { "format": "uri", "type": "string" } }, "required": [ "file_id", "upload_url", "upload_method", "upload_headers", "expires_at" ], "type": "object" } } }, "description": "Upload intent created", "headers": { "Location": { "description": "Canonical URL of the durable resource", "schema": { "format": "uri", "type": "string" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "example": { "code": "idempotency_conflict", "detail": "The idempotency key was already used with a different request.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 409, "title": "Idempotency conflict", "type": "https://getmd.xyz/problems/idempotency_conflict" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "example": { "code": "validation_failed", "detail": "One or more request fields are invalid.", "field_errors": [ { "code": "invalid_url", "detail": "URL must use HTTPS.", "field": "source.url" } ], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 422, "title": "Validation failed", "type": "https://getmd.xyz/problems/validation_failed" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Create a direct-upload intent", "tags": [ "Files" ] } }, "/v1/usage": { "get": { "operationId": "getUsage", "responses": { "200": { "content": { "application/json": { "example": { "account_status": "active", "costs": { "billable_cost_microusd": 250000, "credits_microusd": 0, "currency": "USD", "internal_cost_microusd": 50000, "net_due_microusd": 250000, "provider_cost_microusd": 125000, "refunds_microusd": 0 }, "input_bytes": 1048576, "jobs_created": 12, "limits": { "concurrency": 10, "input_bytes": 10737418240, "jobs": 10000, "spend_cap_microusd": 50000000 }, "output_bytes": 262144, "period_end": "2026-09-01T00:00:00.000Z", "period_start": "2026-08-01T00:00:00.000Z", "plan": "developer", "units": [ { "billable": 12, "credited": 0, "estimated": 0, "finalized": 12, "pending": 0, "unit": "jobs" }, { "billable": 1048576, "credited": 0, "estimated": 0, "finalized": 1048576, "pending": 0, "unit": "input_bytes" }, { "billable": 262144, "credited": 0, "estimated": 0, "finalized": 262144, "pending": 0, "unit": "output_bytes" } ], "warnings": [] }, "schema": { "properties": { "account_status": { "enum": [ "active", "grace", "suspended", "canceled" ], "type": "string" }, "costs": { "properties": { "billable_cost_microusd": { "minimum": 0, "type": "integer" }, "credits_microusd": { "minimum": 0, "type": "integer" }, "currency": { "enum": [ "USD" ], "type": "string" }, "internal_cost_microusd": { "minimum": 0, "type": "integer" }, "net_due_microusd": { "minimum": 0, "type": "integer" }, "provider_cost_microusd": { "minimum": 0, "type": "integer" }, "refunds_microusd": { "minimum": 0, "type": "integer" } }, "required": [ "currency", "provider_cost_microusd", "internal_cost_microusd", "billable_cost_microusd", "credits_microusd", "refunds_microusd", "net_due_microusd" ], "type": "object" }, "input_bytes": { "minimum": 0, "type": "integer" }, "jobs_created": { "minimum": 0, "type": "integer" }, "limits": { "properties": { "concurrency": { "exclusiveMinimum": 0, "type": "integer" }, "input_bytes": { "minimum": 0, "type": "integer" }, "jobs": { "minimum": 0, "type": "integer" }, "spend_cap_microusd": { "minimum": 0, "type": [ "integer", "null" ] } }, "required": [ "jobs", "input_bytes", "concurrency", "spend_cap_microusd" ], "type": "object" }, "output_bytes": { "minimum": 0, "type": "integer" }, "period_end": { "format": "date-time", "type": "string" }, "period_start": { "format": "date-time", "type": "string" }, "plan": { "enum": [ "metered_beta", "free", "developer", "team", "enterprise" ], "type": "string" }, "units": { "items": { "properties": { "billable": { "minimum": 0, "type": "number" }, "credited": { "minimum": 0, "type": "number" }, "estimated": { "minimum": 0, "type": "number" }, "finalized": { "minimum": 0, "type": "number" }, "pending": { "minimum": 0, "type": "number" }, "unit": { "enum": [ "jobs", "uploaded_bytes", "input_bytes", "extracted_pages", "extracted_characters", "media_minutes", "enrichment_tokens", "stored_gigabyte_days", "output_bytes" ], "type": "string" } }, "required": [ "unit", "estimated", "pending", "finalized", "credited", "billable" ], "type": "object" }, "type": "array" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "period_start", "period_end", "jobs_created", "input_bytes", "output_bytes", "plan", "account_status", "units", "costs", "warnings", "limits" ], "type": "object" } } }, "description": "Usage counters and limits", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Get usage for the current billing period", "tags": [ "Usage" ] } }, "/v1/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoints", "parameters": [ { "description": "Opaque pagination cursor", "in": "query", "name": "cursor", "required": false, "schema": { "description": "Opaque pagination cursor", "maxLength": 512, "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "created_at": "2026-08-23T12:00:00.000Z", "description": "Production agent completion events", "events": [ "job.succeeded", "job.failed", "output.created" ], "id": "wh_01K3M8H6DN5ZG2Q8FJTX", "secret_last_four": "A9zQ", "status": "active", "updated_at": "2026-08-23T12:00:00.000Z", "url": "https://agent.example.com/getmd/events" } ], "page": { "has_more": false, "next_cursor": null } }, "schema": { "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "description": { "maxLength": 200, "type": "string" }, "events": { "items": { "enum": [ "job.queued", "job.processing", "job.succeeded", "job.failed", "job.canceled", "output.created", "file.rejected", "quota.warning", "quota.exceeded", "billing.usage_finalized", "billing.invoice_created", "billing.credit_created", "billing.refund_created", "billing.account_updated" ], "type": "string" }, "maxItems": 14, "minItems": 1, "type": "array" }, "id": { "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "secret_last_four": { "maxLength": 4, "minLength": 4, "type": "string" }, "status": { "enum": [ "active", "paused" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "id", "url", "description", "events", "status", "secret_last_four", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "page": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "description": "Opaque pagination cursor", "maxLength": 512, "minLength": 1, "type": [ "string", "null" ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "page" ], "type": "object" } } }, "description": "Webhook endpoint page", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "List registered webhook endpoints", "tags": [ "Webhooks" ] }, "post": { "operationId": "createWebhookEndpoint", "requestBody": { "content": { "application/json": { "example": { "description": "Production agent completion events", "events": [ "job.succeeded", "job.failed", "output.created" ], "url": "https://agent.example.com/getmd/events" }, "schema": { "properties": { "description": { "default": "", "maxLength": 200, "type": "string" }, "events": { "items": { "enum": [ "job.queued", "job.processing", "job.succeeded", "job.failed", "job.canceled", "output.created", "file.rejected", "quota.warning", "quota.exceeded", "billing.usage_finalized", "billing.invoice_created", "billing.credit_created", "billing.refund_created", "billing.account_updated" ], "type": "string" }, "maxItems": 14, "minItems": 1, "type": "array" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url", "events" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "endpoint": { "created_at": "2026-08-23T12:00:00.000Z", "description": "Production agent completion events", "events": [ "job.succeeded", "job.failed", "output.created" ], "id": "wh_01K3M8H6DN5ZG2Q8FJTX", "secret_last_four": "A9zQ", "status": "active", "updated_at": "2026-08-23T12:00:00.000Z", "url": "https://agent.example.com/getmd/events" }, "secret": "whsec_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "schema": { "properties": { "endpoint": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "description": { "maxLength": 200, "type": "string" }, "events": { "items": { "enum": [ "job.queued", "job.processing", "job.succeeded", "job.failed", "job.canceled", "output.created", "file.rejected", "quota.warning", "quota.exceeded", "billing.usage_finalized", "billing.invoice_created", "billing.credit_created", "billing.refund_created", "billing.account_updated" ], "type": "string" }, "maxItems": 14, "minItems": 1, "type": "array" }, "id": { "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "secret_last_four": { "maxLength": 4, "minLength": 4, "type": "string" }, "status": { "enum": [ "active", "paused" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "id", "url", "description", "events", "status", "secret_last_four", "created_at", "updated_at" ], "type": "object" }, "secret": { "pattern": "^whsec_[A-Za-z0-9_-]{32,}$/u", "type": "string" } }, "required": [ "endpoint", "secret" ], "type": "object" } } }, "description": "Endpoint registered; the signing secret is returned only in this response", "headers": { "Location": { "description": "Canonical URL of the durable resource", "schema": { "format": "uri", "type": "string" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "example": { "code": "validation_failed", "detail": "One or more request fields are invalid.", "field_errors": [ { "code": "invalid_url", "detail": "URL must use HTTPS.", "field": "source.url" } ], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 422, "title": "Validation failed", "type": "https://getmd.xyz/problems/validation_failed" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Register a signed webhook endpoint", "tags": [ "Webhooks" ] } }, "/v1/webhook-endpoints/{endpoint_id}": { "delete": { "operationId": "deleteWebhookEndpoint", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "example": "wh_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "responses": { "204": { "description": "Endpoint deleted", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ] }, "patch": { "operationId": "updateWebhookEndpoint", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "example": "wh_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "events": [ "job.succeeded", "job.failed" ] }, "schema": { "properties": { "description": { "default": "", "maxLength": 200, "type": "string" }, "events": { "items": { "enum": [ "job.queued", "job.processing", "job.succeeded", "job.failed", "job.canceled", "output.created", "file.rejected", "quota.warning", "quota.exceeded", "billing.usage_finalized", "billing.invoice_created", "billing.credit_created", "billing.refund_created", "billing.account_updated" ], "type": "string" }, "maxItems": 14, "minItems": 1, "type": "array" }, "url": { "format": "uri", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "created_at": "2026-08-23T12:00:00.000Z", "description": "Production agent completion events", "events": [ "job.succeeded", "job.failed", "output.created" ], "id": "wh_01K3M8H6DN5ZG2Q8FJTX", "secret_last_four": "A9zQ", "status": "active", "updated_at": "2026-08-23T12:00:00.000Z", "url": "https://agent.example.com/getmd/events" }, "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "description": { "maxLength": 200, "type": "string" }, "events": { "items": { "enum": [ "job.queued", "job.processing", "job.succeeded", "job.failed", "job.canceled", "output.created", "file.rejected", "quota.warning", "quota.exceeded", "billing.usage_finalized", "billing.invoice_created", "billing.credit_created", "billing.refund_created", "billing.account_updated" ], "type": "string" }, "maxItems": 14, "minItems": 1, "type": "array" }, "id": { "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "secret_last_four": { "maxLength": 4, "minLength": 4, "type": "string" }, "status": { "enum": [ "active", "paused" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "id", "url", "description", "events", "status", "secret_last_four", "created_at", "updated_at" ], "type": "object" } } }, "description": "Updated endpoint" }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "example": { "code": "validation_failed", "detail": "One or more request fields are invalid.", "field_errors": [ { "code": "invalid_url", "detail": "URL must use HTTPS.", "field": "source.url" } ], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 422, "title": "Validation failed", "type": "https://getmd.xyz/problems/validation_failed" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Update a webhook URL, description, or event subscriptions", "tags": [ "Webhooks" ] } }, "/v1/webhook-endpoints/{endpoint_id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "example": "wh_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" } }, { "description": "Opaque pagination cursor", "in": "query", "name": "cursor", "required": false, "schema": { "description": "Opaque pagination cursor", "maxLength": 512, "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "attempts": 1, "completed_at": "2026-08-23T12:00:00.000Z", "created_at": "2026-08-23T12:00:00.000Z", "endpoint_id": "wh_01K3M8H6DN5ZG2Q8FJTX", "event_id": "evt_01K3M8H6DN5ZG2Q8FJTX", "event_type": "job.succeeded", "id": "whd_01K3M8H6DN5ZG2Q8FJTX", "last_error_code": null, "next_attempt_at": null, "response_preview": "", "response_status": 204, "status": "succeeded" } ], "page": { "has_more": false, "next_cursor": null } }, "schema": { "properties": { "data": { "items": { "properties": { "attempts": { "minimum": 0, "type": "integer" }, "completed_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "endpoint_id": { "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "event_id": { "pattern": "^evt_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "event_type": { "enum": [ "job.queued", "job.processing", "job.succeeded", "job.failed", "job.canceled", "output.created", "file.rejected", "quota.warning", "quota.exceeded", "billing.usage_finalized", "billing.invoice_created", "billing.credit_created", "billing.refund_created", "billing.account_updated" ], "type": "string" }, "id": { "pattern": "^whd_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "last_error_code": { "maxLength": 100, "type": [ "string", "null" ] }, "next_attempt_at": { "format": "date-time", "type": [ "string", "null" ] }, "response_preview": { "maxLength": 512, "type": [ "string", "null" ] }, "response_status": { "maximum": 599, "minimum": 100, "type": [ "integer", "null" ] }, "status": { "enum": [ "pending", "delivering", "succeeded", "retrying", "dead_letter" ], "type": "string" } }, "required": [ "id", "event_id", "endpoint_id", "event_type", "status", "attempts", "response_status", "response_preview", "last_error_code", "next_attempt_at", "created_at", "completed_at" ], "type": "object" }, "type": "array" }, "page": { "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "description": "Opaque pagination cursor", "maxLength": 512, "minLength": 1, "type": [ "string", "null" ] } }, "required": [ "next_cursor", "has_more" ], "type": "object" } }, "required": [ "data", "page" ], "type": "object" } } }, "description": "Webhook delivery page" }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "List redacted delivery attempts", "tags": [ "Webhooks" ] } }, "/v1/webhook-endpoints/{endpoint_id}/deliveries/{delivery_id}/replay": { "post": { "operationId": "replayWebhookDelivery", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "example": "wh_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" } }, { "in": "path", "name": "delivery_id", "required": true, "schema": { "example": "whd_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^whd_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "example": { "status": "pending" }, "schema": { "properties": { "status": { "enum": [ "pending" ], "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Delivery queued for replay" }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Replay a dead-lettered delivery with the same event ID", "tags": [ "Webhooks" ] } }, "/v1/webhook-endpoints/{endpoint_id}/pause": { "post": { "operationId": "pauseWebhookEndpoint", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "example": "wh_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "created_at": "2026-08-23T12:00:00.000Z", "description": "Production agent completion events", "events": [ "job.succeeded", "job.failed", "output.created" ], "id": "wh_01K3M8H6DN5ZG2Q8FJTX", "secret_last_four": "A9zQ", "status": "paused", "updated_at": "2026-08-23T12:00:00.000Z", "url": "https://agent.example.com/getmd/events" }, "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "description": { "maxLength": 200, "type": "string" }, "events": { "items": { "enum": [ "job.queued", "job.processing", "job.succeeded", "job.failed", "job.canceled", "output.created", "file.rejected", "quota.warning", "quota.exceeded", "billing.usage_finalized", "billing.invoice_created", "billing.credit_created", "billing.refund_created", "billing.account_updated" ], "type": "string" }, "maxItems": 14, "minItems": 1, "type": "array" }, "id": { "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "secret_last_four": { "maxLength": 4, "minLength": 4, "type": "string" }, "status": { "enum": [ "active", "paused" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "id", "url", "description", "events", "status", "secret_last_four", "created_at", "updated_at" ], "type": "object" } } }, "description": "Endpoint paused" }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Pause webhook delivery", "tags": [ "Webhooks" ] } }, "/v1/webhook-endpoints/{endpoint_id}/resume": { "post": { "operationId": "resumeWebhookEndpoint", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "example": "wh_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "created_at": "2026-08-23T12:00:00.000Z", "description": "Production agent completion events", "events": [ "job.succeeded", "job.failed", "output.created" ], "id": "wh_01K3M8H6DN5ZG2Q8FJTX", "secret_last_four": "A9zQ", "status": "active", "updated_at": "2026-08-23T12:00:00.000Z", "url": "https://agent.example.com/getmd/events" }, "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "description": { "maxLength": 200, "type": "string" }, "events": { "items": { "enum": [ "job.queued", "job.processing", "job.succeeded", "job.failed", "job.canceled", "output.created", "file.rejected", "quota.warning", "quota.exceeded", "billing.usage_finalized", "billing.invoice_created", "billing.credit_created", "billing.refund_created", "billing.account_updated" ], "type": "string" }, "maxItems": 14, "minItems": 1, "type": "array" }, "id": { "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "secret_last_four": { "maxLength": 4, "minLength": 4, "type": "string" }, "status": { "enum": [ "active", "paused" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "id", "url", "description", "events", "status", "secret_last_four", "created_at", "updated_at" ], "type": "object" } } }, "description": "Endpoint active" }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Resume webhook delivery", "tags": [ "Webhooks" ] } }, "/v1/webhook-endpoints/{endpoint_id}/rotate-secret": { "post": { "operationId": "rotateWebhookEndpointSecret", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "example": "wh_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "endpoint": { "created_at": "2026-08-23T12:00:00.000Z", "description": "Production agent completion events", "events": [ "job.succeeded", "job.failed", "output.created" ], "id": "wh_01K3M8H6DN5ZG2Q8FJTX", "secret_last_four": "A9zQ", "status": "active", "updated_at": "2026-08-23T12:00:00.000Z", "url": "https://agent.example.com/getmd/events" }, "secret": "whsec_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" }, "schema": { "properties": { "endpoint": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "description": { "maxLength": 200, "type": "string" }, "events": { "items": { "enum": [ "job.queued", "job.processing", "job.succeeded", "job.failed", "job.canceled", "output.created", "file.rejected", "quota.warning", "quota.exceeded", "billing.usage_finalized", "billing.invoice_created", "billing.credit_created", "billing.refund_created", "billing.account_updated" ], "type": "string" }, "maxItems": 14, "minItems": 1, "type": "array" }, "id": { "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" }, "secret_last_four": { "maxLength": 4, "minLength": 4, "type": "string" }, "status": { "enum": [ "active", "paused" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "id", "url", "description", "events", "status", "secret_last_four", "created_at", "updated_at" ], "type": "object" }, "secret": { "pattern": "^whsec_[A-Za-z0-9_-]{32,}$/u", "type": "string" } }, "required": [ "endpoint", "secret" ], "type": "object" } } }, "description": "Secret rotated; the new secret is returned only in this response" }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Rotate the endpoint signing secret", "tags": [ "Webhooks" ] } }, "/v1/webhook-endpoints/{endpoint_id}/test": { "post": { "operationId": "testWebhookEndpoint", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "example": "wh_01K3M8H6DN5ZG2Q8FJTX", "pattern": "^wh_[A-Za-z0-9_-]{12,}$/u", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "example": { "deliveries": 1, "event_id": "evt_01K3M8H6DN5ZG2Q8FJTX" }, "schema": { "properties": { "deliveries": { "minimum": 0, "type": "integer" }, "event_id": { "pattern": "^evt_[A-Za-z0-9_-]{12,}$/u", "type": "string" } }, "required": [ "event_id", "deliveries" ], "type": "object" } } }, "description": "Test event queued" }, "401": { "content": { "application/json": { "example": { "code": "unauthorized", "detail": "Provide a valid API credential.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 401, "title": "Authentication required", "type": "https://getmd.xyz/problems/unauthorized" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "example": { "code": "forbidden", "detail": "The credential does not grant this operation.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 403, "title": "Permission denied", "type": "https://getmd.xyz/problems/forbidden" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "example": { "code": "not_found", "detail": "The requested resource does not exist or is not accessible.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 404, "title": "Resource not found", "type": "https://getmd.xyz/problems/not_found" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "413": { "content": { "application/json": { "example": { "code": "payload_too_large", "detail": "The request body exceeds the public API limit.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 413, "title": "Payload too large", "type": "https://getmd.xyz/problems/payload_too_large" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "415": { "content": { "application/json": { "example": { "code": "unsupported_media_type", "detail": "Content-Type must be application/json.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": false, "status": 415, "title": "Unsupported media type", "type": "https://getmd.xyz/problems/unsupported_media_type" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "429": { "content": { "application/json": { "example": { "code": "rate_limited", "detail": "Retry after the duration in the Retry-After header.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 429, "title": "Rate limit exceeded", "type": "https://getmd.xyz/problems/rate_limited" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "Retry-After": { "description": "Seconds before polling or retrying", "schema": { "minimum": 1, "type": "integer" } }, "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } }, "500": { "content": { "application/json": { "example": { "code": "internal_error", "detail": "The request could not be completed.", "field_errors": [], "request_id": "req_01K3M8H6DN5ZG2Q8FJTX", "retryable": true, "status": 500, "title": "Internal error", "type": "https://getmd.xyz/problems/internal_error" }, "schema": { "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$/u", "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field_errors": { "default": [], "items": { "properties": { "code": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "field": { "minLength": 1, "type": "string" } }, "required": [ "field", "code", "detail" ], "type": "object" }, "type": "array" }, "request_id": { "description": "Request correlation identifier", "maxLength": 128, "minLength": 8, "type": "string" }, "retryable": { "type": "boolean" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "minLength": 1, "type": "string" }, "type": { "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "request_id", "retryable" ], "type": "object" } } }, "description": "Problem details", "headers": { "X-Request-Id": { "description": "Request correlation identifier", "schema": { "type": "string" } } } } }, "summary": "Queue a signed test event", "tags": [ "Webhooks" ] } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "description": "Production", "url": "https://api.getmd.xyz" } ], "tags": [ { "name": "Capabilities" }, { "name": "Files" }, { "name": "Jobs" }, { "name": "Outputs" }, { "name": "Usage" }, { "name": "Webhooks" } ], "webhooks": {} }