Lumen
Reference

HTTP API

Generated endpoint, request, response, authentication, and schema reference.

The HTTP API is generated from FastAPI's canonical OpenAPI document. Browser commands use the generated client; this page does not define a second contract.

  • Contract title: Lumen API
  • Contract version: 0.0.0
  • Endpoint count: 10

Endpoints

GET /api/development-project

Development Project

Authentication: Required by the named OpenAPI security scheme.

Responses

StatusContractDescription
200ProjectProjectionSuccessful Response
401ErrorDetailAuthentication failed.

GET /api/projects/{project_id}

Project Projection

Authentication: Required by the named OpenAPI security scheme.

Parameters

NameLocationRequiredTypeConstraints
project_idpathyesstring—

Responses

StatusContractDescription
200ProjectProjectionSuccessful Response
401ErrorDetailAuthentication failed.
404ErrorDetailThe resource was not found.
422HTTPValidationErrorValidation Error

GET /api/projects/{project_id}/artifacts/{artifact_id}

Artifact Content

Authentication: Required by the named OpenAPI security scheme.

Parameters

NameLocationRequiredTypeConstraints
project_idpathyesstring—
artifact_idpathyesstring—

Responses

StatusContractDescription
200stringVerified immutable artifact bytes.
401ErrorDetailAuthentication failed.
404ErrorDetailThe resource was not found.
422HTTPValidationErrorValidation Error
503ErrorDetailCanonical bytes are unavailable.

GET /api/projects/{project_id}/events

Project Events

Authentication: Required by the named OpenAPI security scheme.

Parameters

NameLocationRequiredTypeConstraints
project_idpathyesstring—
afterquerynostring | null—
followquerynoboolean—
Last-Event-IDheadernostring | null—

Responses

StatusContractDescription
200stringSSE frames whose data field is one serialized DomainEvent object.
400ErrorDetailThe event cursor is invalid.
401ErrorDetailAuthentication failed.
422HTTPValidationErrorValidation Error

GET /api/projects/{project_id}/evidence/{evidence_ref_id}

Evidence Projection

Authentication: Required by the named OpenAPI security scheme.

Parameters

NameLocationRequiredTypeConstraints
project_idpathyesstring—
evidence_ref_idpathyesstring—

Responses

StatusContractDescription
200EvidenceProjectionSuccessful Response
401ErrorDetailAuthentication failed.
404ErrorDetailThe resource was not found.
422HTTPValidationErrorValidation Error
503ErrorDetailCanonical bytes are unavailable.

POST /api/projects/{project_id}/runs

Research Run

Authentication: Required by the named OpenAPI security scheme.

Parameters

NameLocationRequiredTypeConstraints
project_idpathyesstring—

Request body: required; CreateResearchRunCommand

Responses

StatusContractDescription
200CommandAccepted | CommandRejectedSuccessful Response
401ErrorDetailAuthentication failed.
422HTTPValidationErrorValidation Error

GET /api/projects/{project_id}/runs/{run_id}/story

Research Story

Authentication: Required by the named OpenAPI security scheme.

Parameters

NameLocationRequiredTypeConstraints
project_idpathyesstring—
run_idpathyesstring—

Responses

StatusContractDescription
200ResearchStorySuccessful Response
401ErrorDetailAuthentication failed.
404ErrorDetailThe resource was not found.
422HTTPValidationErrorValidation Error

PUT /api/projects/{project_id}/settings

Project Settings

Authentication: Required by the named OpenAPI security scheme.

Parameters

NameLocationRequiredTypeConstraints
project_idpathyesstring—

Request body: required; UpdateProjectSettingsCommand

Responses

StatusContractDescription
200CommandAccepted | CommandRejectedSuccessful Response
401ErrorDetailAuthentication failed.
422HTTPValidationErrorValidation Error

GET /health/live

Live Health

Authentication: No bearer credential is declared for this endpoint.

Responses

StatusContractDescription
200HealthStatusSuccessful Response

GET /health/ready

Ready Health

Authentication: No bearer credential is declared for this endpoint.

Responses

StatusContractDescription
200HealthStatusSuccessful Response

Schemas

ArtifactId

Type: string Constraints: pattern ^art_[0-9a-f]{32}$

ArtifactManifest

FieldRequiredTypeConstraints/default
artifact_idyesArtifactIdpattern ^art_[0-9a-f]{32}$
created_atyesstring—
digestyesstringpattern ^sha256:[0-9a-f]{64}$
media_typeyesstringminimum length 1; maximum length 255
producing_attempt_idyesAttemptIdpattern ^att_[0-9a-f]{32}$
project_idyesProjectIdpattern ^prj_[0-9a-f]{32}$
size_bytesyesintegerminimum 0.0
storage_keyyesstringminimum length 1; maximum length 1024
workspace_idyesWorkspaceIdpattern ^wsp_[0-9a-f]{32}$

AttemptId

Type: string Constraints: pattern ^att_[0-9a-f]{32}$

BlockId

Type: string Constraints: pattern ^blk_[0-9a-f]{32}$

BlockRevisionId

Type: string Constraints: pattern ^rev_[0-9a-f]{32}$

ClaimId

Type: string Constraints: pattern ^clm_[0-9a-f]{32}$

ClaimRevisionId

Type: string Constraints: pattern ^crv_[0-9a-f]{32}$

CommandAccepted

FieldRequiredTypeConstraints/default
aggregate_idyesstring—
aggregate_versionyesintegerminimum 1.0
command_idyesCommandIdpattern ^cmd_[0-9a-f]{32}$
first_event_cursoryesCursorpattern ^c1_[A-Za-z0-9_-]{11}$
statusnoacceptedfixed value accepted; default "accepted"

CommandId

Type: string Constraints: pattern ^cmd_[0-9a-f]{32}$

CommandRejected

FieldRequiredTypeConstraints/default
codeyesstringpattern ^[a-z][a-z0-9_.-]+$
command_idyesCommandIdpattern ^cmd_[0-9a-f]{32}$
messageyesstringminimum length 1; maximum length 500
observed_versionnointeger | nullinteger: minimum 1.0
retry_after_msnointeger | nullinteger: minimum 0.0
retryablenobooleandefault false
statusnorejectedfixed value rejected; default "rejected"

CreateResearchRunCommand

FieldRequiredTypeConstraints/default
command_idyesCommandIdpattern ^cmd_[0-9a-f]{32}$
idempotency_keyyesstringminimum length 8; maximum length 128
payloadyesCreateResearchRunPayload—

CreateResearchRunPayload

FieldRequiredTypeConstraints/default
objectiveyesstringminimum length 12; maximum length 4000

Cursor

Type: string Constraints: pattern ^c1_[A-Za-z0-9_-]{11}$

DocumentId

Type: string Constraints: pattern ^doc_[0-9a-f]{32}$

DomainEvent

FieldRequiredTypeConstraints/default
actoryesEventActor—
aggregate_idyesstring—
aggregate_typeyesstring—
aggregate_versionyesintegerminimum 1.0
causation_idyesstring—
correlation_idyesstring—
cursoryesCursorpattern ^c1_[A-Za-z0-9_-]{11}$
event_idyesEventIdpattern ^eve_[0-9a-f]{32}$
event_typeyesstringpattern ^[a-z][a-z0-9_.-]+$
occurred_atyesstring—
payloadyesobject—
project_idyesProjectIdpattern ^prj_[0-9a-f]{32}$
schema_versionno1fixed value 1; default 1
trace_idyesstring—
workspace_idyesWorkspaceIdpattern ^wsp_[0-9a-f]{32}$

ErrorDetail

FieldRequiredTypeConstraints/default
codeyesstringpattern ^[a-z][a-z0-9_.-]+$
messageyesstringminimum length 1; maximum length 500
retry_after_msnointeger | nullinteger: minimum 0.0
retryablenobooleandefault false

EventActor

FieldRequiredTypeConstraints/default
idyesstring—
typeyeshuman | system | attemptvalues human, system, attempt

EventId

Type: string Constraints: pattern ^eve_[0-9a-f]{32}$

EvidenceProjection

FieldRequiredTypeConstraints/default
artifactyesArtifactManifest—
content_urlyesstring—
evidence_ref_idyesEvidenceRefIdpattern ^evr_[0-9a-f]{32}$
locatoryesobject—
target_kindyesartifactfixed value artifact

EvidenceRefId

Type: string Constraints: pattern ^evr_[0-9a-f]{32}$

ExecutionId

Type: string Constraints: pattern ^exe_[0-9a-f]{32}$

ExecutionOutputId

Type: string Constraints: pattern ^out_[0-9a-f]{32}$

HTTPValidationError

FieldRequiredTypeConstraints/default
detailnoarray of ValidationError—

HealthStatus

FieldRequiredTypeConstraints/default
statusnookfixed value ok; default "ok"

JsonValue

Type: object Constraints: —

PlanVersionId

Type: string Constraints: pattern ^pln_[0-9a-f]{32}$

ProjectId

Type: string Constraints: pattern ^prj_[0-9a-f]{32}$

ProjectProjection

FieldRequiredTypeConstraints/default
nameyesstring—
project_idyesProjectIdpattern ^prj_[0-9a-f]{32}$
settingsyesProjectSettings—
versionyesintegerminimum 1.0
workspace_idyesWorkspaceIdpattern ^wsp_[0-9a-f]{32}$

ProjectSettings

FieldRequiredTypeConstraints/default
inspector_collapsednobooleandefault false
inspector_widthnointegerminimum 320.0; maximum 480.0; default 360
navigator_collapsednobooleandefault false
navigator_widthnointegerminimum 216.0; maximum 384.0; default 248
themenosystem | light | darkvalues system, light, dark; default "system"

ResearchStory

FieldRequiredTypeConstraints/default
artifactyesStoryArtifact—
attemptyesStoryAttempt—
claimyesStoryClaim—
latest_cursoryesCursorpattern ^c1_[A-Za-z0-9_-]{11}$
notebookyesStoryBlock—
objectiveyesstring—
plan_version_idyesPlanVersionIdpattern ^pln_[0-9a-f]{32}$
project_idyesProjectIdpattern ^prj_[0-9a-f]{32}$
run_idyesRunIdpattern ^run_[0-9a-f]{32}$
taskyesStoryTask—
workspace_idyesWorkspaceIdpattern ^wsp_[0-9a-f]{32}$
writeupyesStoryWriteup—

RunId

Type: string Constraints: pattern ^run_[0-9a-f]{32}$

StoryArtifact

FieldRequiredTypeConstraints/default
content_urlyesstring—
manifestyesArtifactManifest—

StoryAttempt

FieldRequiredTypeConstraints/default
attempt_idyesAttemptIdpattern ^att_[0-9a-f]{32}$
stateyessucceededfixed value succeeded
summaryyesstring—

StoryBlock

FieldRequiredTypeConstraints/default
block_idyesBlockIdpattern ^blk_[0-9a-f]{32}$
block_revision_idyesBlockRevisionIdpattern ^rev_[0-9a-f]{32}$
document_idyesDocumentIdpattern ^doc_[0-9a-f]{32}$
execution_idyesExecutionIdpattern ^exe_[0-9a-f]{32}$
execution_output_idyesExecutionOutputIdpattern ^out_[0-9a-f]{32}$
output_textyesstring—
sourceyesstring—

StoryClaim

FieldRequiredTypeConstraints/default
claim_idyesClaimIdpattern ^clm_[0-9a-f]{32}$
claim_revision_idyesClaimRevisionIdpattern ^crv_[0-9a-f]{32}$
currentnessyescurrentfixed value current
evidence_ref_idyesEvidenceRefIdpattern ^evr_[0-9a-f]{32}$
evidence_urlyesstring—
review_statusyesacceptedfixed value accepted
textyesstring—
validityyesvalid-for-pinned-inputsfixed value valid-for-pinned-inputs

StoryTask

FieldRequiredTypeConstraints/default
objectiveyesstring—
phaseyescompletedfixed value completed
task_idyesTaskIdpattern ^tsk_[0-9a-f]{32}$
titleyesstring—

StoryWriteup

FieldRequiredTypeConstraints/default
block_revision_idyesBlockRevisionIdpattern ^rev_[0-9a-f]{32}$
document_idyesDocumentIdpattern ^doc_[0-9a-f]{32}$
markdownyesstring—

TaskId

Type: string Constraints: pattern ^tsk_[0-9a-f]{32}$

UpdateProjectSettingsCommand

FieldRequiredTypeConstraints/default
command_idyesCommandIdpattern ^cmd_[0-9a-f]{32}$
idempotency_keyyesstringminimum length 8; maximum length 128
payloadyesUpdateProjectSettingsPayload—

UpdateProjectSettingsPayload

FieldRequiredTypeConstraints/default
expected_versionyesintegerminimum 1.0
settingsyesProjectSettings—

ValidationError

FieldRequiredTypeConstraints/default
ctxnoobject—
inputnoobject—
locyesarray of string | integer—
msgyesstring—
typeyesstring—

WorkspaceId

Type: string Constraints: pattern ^wsp_[0-9a-f]{32}$

Reference

Use generated HTTP, configuration, identifier, state, event, limit, and CLI contracts.

Settings and environment

Generated process configuration names, types, defaults, and validation boundaries.

On this page

EndpointsGET /api/development-projectGET /api/projects/{project_id}GET /api/projects/{project_id}/artifacts/{artifact_id}GET /api/projects/{project_id}/eventsGET /api/projects/{project_id}/evidence/{evidence_ref_id}POST /api/projects/{project_id}/runsGET /api/projects/{project_id}/runs/{run_id}/storyPUT /api/projects/{project_id}/settingsGET /health/liveGET /health/readySchemasArtifactIdArtifactManifestAttemptIdBlockIdBlockRevisionIdClaimIdClaimRevisionIdCommandAcceptedCommandIdCommandRejectedCreateResearchRunCommandCreateResearchRunPayloadCursorDocumentIdDomainEventErrorDetailEventActorEventIdEvidenceProjectionEvidenceRefIdExecutionIdExecutionOutputIdHTTPValidationErrorHealthStatusJsonValuePlanVersionIdProjectIdProjectProjectionProjectSettingsResearchStoryRunIdStoryArtifactStoryAttemptStoryBlockStoryClaimStoryTaskStoryWriteupTaskIdUpdateProjectSettingsCommandUpdateProjectSettingsPayloadValidationErrorWorkspaceId