JobResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/superdocs-app/json-schema/superdocs-app-job-response-schema.json",
  "title": "JobResponse",
  "description": "Status and details of an async job.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/superdocs-app-openapi.json#/components/schemas/JobResponse",
  "properties": {
    "job_id": {
      "type": "string",
      "title": "Job Id",
      "description": "Unique job identifier. Use this to poll for status updates."
    },
    "organization_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Organization Id",
      "description": "Organization that owns this job (null for user jobs)."
    },
    "user_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "User Id",
      "description": "User that owns this job (null for organization jobs)."
    },
    "session_id": {
      "type": "string",
      "title": "Session Id",
      "description": "Session associated with this job."
    },
    "job_type": {
      "type": "string",
      "title": "Job Type",
      "description": "Type of job: 'chat' or 'attachment_processing'."
    },
    "status": {
      "type": "string",
      "title": "Status",
      "description": "Current status: 'pending', 'in_progress', 'awaiting_approval', 'completed', 'failed', or 'cancelled'."
    },
    "created_at": {
      "type": "string",
      "title": "Created At",
      "description": "ISO 8601 timestamp when the job was created."
    },
    "updated_at": {
      "type": "string",
      "title": "Updated At",
      "description": "ISO 8601 timestamp of the last status change."
    },
    "progress": {
      "type": "integer",
      "title": "Progress",
      "description": "Progress percentage (0-100)."
    },
    "result": {
      "anyOf": [
        {
          "$ref": "#/$defs/JobResult"
        },
        {
          "type": "null"
        }
      ],
      "description": "Job output. Present when status is 'completed'. Contains AI response and document changes for chat jobs."
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Error",
      "description": "Error message. Present when status is 'failed'."
    },
    "metadata": {
      "anyOf": [
        {
          "$ref": "#/$defs/JobMetadata"
        },
        {
          "type": "null"
        }
      ],
      "description": "Job metadata and context. Contains pending_changes when status is 'awaiting_approval'."
    }
  },
  "type": "object",
  "required": [
    "job_id",
    "session_id",
    "job_type",
    "status",
    "created_at",
    "updated_at",
    "progress"
  ],
  "$defs": {
    "ActivePromotionInfo": {
      "properties": {
        "redemption_id": {
          "type": "string",
          "title": "Redemption Id",
          "description": "Unique identifier for this promotion grant."
        },
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Human-friendly promotion name (e.g., 'YC SUS India 2026 cohort')."
        },
        "ops_remaining": {
          "type": "integer",
          "title": "Ops Remaining",
          "description": "Operations still available in this promotion bucket."
        },
        "ops_granted": {
          "type": "integer",
          "title": "Ops Granted",
          "description": "Total operations originally granted by this redemption."
        },
        "expires_at": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Expires At",
          "description": "ISO 8601 expiry timestamp. Null if the credits never expire."
        }
      },
      "additionalProperties": true,
      "type": "object",
      "required": [
        "redemption_id",
        "name",
        "ops_remaining",
        "ops_granted"
      ],
      "title": "ActivePromotionInfo",
      "description": "A single active (drawable) promotion belonging to the authenticated user."
    },
    "DocumentChanges": {
      "properties": {
        "updated_html": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Updated Html",
          "description": "Full updated document HTML with data-chunk-id attributes. Apply this to your editor to sync the document. Present in 'full' response mode (default); null in 'compact' mode."
        },
        "version_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Version Id",
          "description": "Document version identifier. Changes on every modification."
        },
        "changes_summary": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Changes Summary",
          "description": "Human-readable summary of what was changed."
        },
        "requires_approval": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Requires Approval",
          "description": "If true, changes need review via the approve endpoint before being applied."
        },
        "pending_changes": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/PendingChange"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Pending Changes",
          "description": "Proposed changes awaiting approval. Present when requires_approval is true."
        },
        "changes": {
          "anyOf": [
            {
              "items": {
                "additionalProperties": true,
                "type": "object"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Changes",
          "description": "History of individual changes applied during this request."
        },
        "chunk_diffs": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/PendingChange"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Chunk Diffs",
          "description": "Per-section before/after content for changes that were applied this turn. Present in 'compact' response mode (when updated_html is null) so the agent can verify what was modified without paying token cost for the full document. Same shape as pending_changes."
        },
        "concurrent_merges": {
          "anyOf": [
            {
              "items": {
                "additionalProperties": true,
                "type": "object"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Concurrent Merges",
          "description": "Present ONLY when this request's edit collided with a concurrent edit: another session/chat committed a different change to the same section(s) while this request was processing, and the two were merged server-side. One entry per affected document: {document_id, durable_document_id, version, conflicting_sections}. When present, updated_html reflects the merged COMMITTED state — it may differ from the text this response describes; review the affected sections and re-apply anything that was superseded. Absent (null) on every non-conflicting request, including concurrent edits to DIFFERENT sections (those merge cleanly with no data loss and no notice)."
        }
      },
      "additionalProperties": true,
      "type": "object",
      "title": "DocumentChanges",
      "description": "Document modifications produced by the AI assistant."
    },
    "JobMetadata": {
      "properties": {
        "filename": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Filename",
          "description": "Uploaded filename (attachment processing jobs)."
        },
        "file_size": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "File Size",
          "description": "File size in bytes (attachment processing jobs)."
        },
        "content_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Content Type",
          "description": "MIME type of uploaded file (attachment processing jobs)."
        },
        "message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Message",
          "description": "Original user message (chat jobs)."
        },
        "document_html_provided": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Document Html Provided",
          "description": "Whether document HTML was included in the request (chat jobs)."
        },
        "pending_changes": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/PendingChange"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Pending Changes",
          "description": "Proposed changes awaiting approval. Present when job status is 'awaiting_approval'."
        },
        "intermediate_responses": {
          "anyOf": [
            {
              "items": {
                "additionalProperties": true,
                "type": "object"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Intermediate Responses",
          "description": "Progress updates during processing. Each item has: type, content, sequence, timestamp."
        }
      },
      "additionalProperties": true,
      "type": "object",
      "title": "JobMetadata",
      "description": "Job metadata. Contents vary by job type."
    },
    "JobResult": {
      "properties": {
        "response": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Response",
          "description": "AI response text (chat jobs)."
        },
        "session_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Session Id",
          "description": "Session identifier (chat jobs)."
        },
        "document_changes": {
          "anyOf": [
            {
              "$ref": "#/$defs/DocumentChanges"
            },
            {
              "type": "null"
            }
          ],
          "description": "Document modifications (chat jobs)."
        },
        "usage": {
          "anyOf": [
            {
              "$ref": "#/$defs/UsageInfo"
            },
            {
              "type": "null"
            }
          ],
          "description": "Usage tracking data (chat jobs)."
        },
        "attachment_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Attachment Id",
          "description": "Processed attachment identifier (attachment processing jobs)."
        }
      },
      "additionalProperties": true,
      "type": "object",
      "title": "JobResult",
      "description": "Job result data. Structure depends on job type."
    },
    "PendingChange": {
      "properties": {
        "change_id": {
          "type": "string",
          "title": "Change Id",
          "description": "Unique identifier for this proposed change."
        },
        "operation": {
          "type": "string",
          "title": "Operation",
          "description": "Type of change: 'edit', 'create', or 'delete'."
        },
        "chunk_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Chunk Id",
          "description": "Target document section ID being modified or deleted."
        },
        "document_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Document Id",
          "description": "Identifier of the document (tab) this change applies to — lets multi-document integrators attribute each section diff to the right document."
        },
        "old_html": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Old Html",
          "description": "Previous HTML content of the section (for updates)."
        },
        "new_html": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "New Html",
          "description": "Proposed new HTML content (for updates and creates)."
        },
        "ai_explanation": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Ai Explanation",
          "description": "AI-generated explanation of why this change was proposed."
        }
      },
      "additionalProperties": true,
      "type": "object",
      "required": [
        "change_id",
        "operation"
      ],
      "title": "PendingChange",
      "description": "A proposed document change awaiting user approval."
    },
    "UsageInfo": {
      "properties": {
        "monthly_used": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Monthly Used",
          "description": "Total operations used this billing cycle."
        },
        "monthly_limit": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Monthly Limit",
          "description": "Maximum operations allowed per cycle. -1 means unlimited."
        },
        "monthly_remaining": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Monthly Remaining",
          "description": "Operations remaining this cycle. -1 means unlimited."
        },
        "was_billable": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Was Billable",
          "description": "Whether this request counted as a billable operation."
        },
        "ops_charged": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Ops Charged",
          "description": "How many operations this request billed. A large multi-section edit can bill more than one (one per 25 sections edited), so monthly_used can increase by more than 1 between responses."
        },
        "quota_exhausted": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Quota Exhausted",
          "description": "True when you have reached your plan's operation limit with no remaining balance — the current request still completes, but further billable requests pause until you upgrade or your billing cycle resets."
        },
        "subscription_tier": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Subscription Tier",
          "description": "Current subscription tier: 'free', 'plus', 'pro', or 'enterprise'."
        },
        "bucket_used": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Bucket Used",
          "description": "Which bucket this operation drew from: 'tier' or 'promo'. Null for non-billable ops."
        },
        "redemption_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Redemption Id",
          "description": "Redemption grant this op drew from, when bucket_used is 'promo'."
        },
        "promotions": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/ActivePromotionInfo"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Promotions",
          "description": "User's currently-active promotion grants, ordered by oldest-expiring first."
        }
      },
      "additionalProperties": true,
      "type": "object",
      "title": "UsageInfo",
      "description": "Operation usage data for the current billing cycle."
    }
  }
}