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, a service-specific CLI, docs, and optional compatibility diff against a current SDK. Returns 202 with the created run, queue capability details, and a user-facing status message.

Request

cURL

curl -X POST 'https://sourced.sh/api/reports/start' \
  -H 'Authorization: Bearer $SOURCED_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

TypeScript

const response = await fetch("https://sourced.sh/api/reports/start", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SOURCED_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const data = await response.json();

Python

import os
import requests

response = requests.request(
    "POST",
    "https://sourced.sh/api/reports/start",
    headers={"Authorization": f"Bearer {os.environ['SOURCED_API_KEY']}"},
    json={},
)
data = response.json()

Request body

Required.

application/json

Schema

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

Schema

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

Schema

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