reports · version 0.1.0

Start a migration / generation report run

POST /api/reports/start

Submits OpenAPI (and optionally a generator config) for an end-to-end report run: spec validation, TypeScript and Python SDK previews, docs preview, and optional compatibility diff against a current SDK. Returns 202 with the created run, queue capability details, and a user-facing status message.

Request

POST https://sourced.sh/api/reports/start

Request body

Required.

application/json

StartReportInput:
  oneOf:
  - option 1:
    type: object
    required: openapiText
    properties:
      mode: string enum flagship | custom | openapi
      projectId: string
      projectName: string
      openapiFileName: string
      configFileName: string
      oldSdkFileName: string
        Optional filename for current SDK source text used in compatibility diff reports.
      openapiText (required): string
        OpenAPI 3.x source (yaml or json), inline.
      configText: string
        Optional generator config. If omitted, Sourced creates a starter config from the OpenAPI paths.
      oldSdkText: string
        Optional current SDK source text used to compare generated SDK surface area and migration risk.
      notes: string
  - option 2:
    type: object
    required: mode, openapiText, configText
    properties:
      mode (required): string enum stainless_compatible | stainless_migration
      projectId: string
      projectName: string
      openapiFileName: string
      configFileName: string
      oldSdkFileName: string
        Optional filename for current SDK source text used in compatibility diff reports.
      openapiText (required): string
        OpenAPI 3.x source (yaml or json), inline.
      configText (required): string
        stainless.yml input required for Stainless migration compatibility runs.
      oldSdkText: string
        Optional current SDK source text used to compare generated SDK surface area and migration risk.
      notes: string

Responses

202

Report run accepted; payload contains the project, created run, queue capabilities, and user-facing message.

application/json

StartReportResponse:
  type: object
  required: project, run, capabilities, message
  properties:
    project (required): Project
      Project:
        type: object
        required: id, name, createdAt
        properties:
          id (required): string
          name (required): string
          apiName: string
          mode: string enum flagship | stainless_compatible | custom | openapi | stainless_migration
            New writes use `flagship` or `stainless_compatible`; legacy `custom`, `openapi`, and `stainless_migration` records may still be returned.
          status: string enum created | active | archived
          createdAt (required): string
          updatedAt: string
          runCount: integer
    run (required): Run
      Run:
        type: object
        required: id, projectId, status, createdAt
        properties:
          id (required): string
          orgId: string
          projectId (required): string
          createdByUserId: string
          status (required): string enum queued | running | blocked | complete | ready | failed | expired | canceled
          mode: string enum flagship | stainless_compatible | custom | openapi | stainless | stainless_migration | reference-sample
          verdict: string enum queued | generated | ready | needs_review | not_ready | needs_worker | needs_setup | failed | canceled
          createdAt (required): string
          completedAt: string
          steps: array
          inputSummary: object
          notes: string
          currentStep: string
          artifactManifest: ArtifactManifest
          updatedAt: string
    capabilities (required): object
      type: object
      required: persistedRuns, hostedWorker, rawUploadStorage, queueConfigured, queued
      properties:
        persistedRuns (required): boolean
        hostedWorker (required): boolean
        rawUploadStorage (required): boolean
        queueConfigured (required): boolean
        queued (required): boolean
        storageProvider: string
        queueProvider: string
        usage: object
        limits: object
    message (required): string

400

401

402

403

429

Hosted report rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.

application/json

Error:
  type: object
  required: error
  properties:
    error (required): string
      Stable machine-readable error code.
    message: string
      Optional human-readable description.

Back to version index