2026-03-13 23:21:55 +00:00
|
|
|
openapi: 3.1.0
|
|
|
|
|
info:
|
|
|
|
|
# Do not change the title, if the title changes, the import paths will be broken
|
|
|
|
|
title: Api
|
|
|
|
|
version: 0.1.0
|
|
|
|
|
description: API specification
|
|
|
|
|
servers:
|
|
|
|
|
- url: /api
|
|
|
|
|
description: Base API path
|
|
|
|
|
tags:
|
|
|
|
|
- name: health
|
|
|
|
|
description: Health operations
|
Task #3: MVP API — payment-gated jobs + demo endpoint
OpenAPI spec (lib/api-spec/openapi.yaml)
- Added POST /jobs, GET /jobs/{id}, GET /demo endpoints
- Added schemas: CreateJobRequest, CreateJobResponse, JobStatusResponse,
InvoiceInfo, JobState, DemoResponse, ErrorResponse
- Ran codegen: generated CreateJobBody, GetJobResponse, RunDemoQueryParams etc.
Jobs router (artifacts/api-server/src/routes/jobs.ts)
- POST /jobs: validates body, creates LNbits eval invoice, inserts job +
invoice in a DB transaction, returns { jobId, evalInvoice }
- GET /jobs/:id: fetches job, calls advanceJob() helper, returns state-
appropriate payload (eval/work invoice, reason, result, errorMessage)
- advanceJob() state machine:
- awaiting_eval_payment: checks LNbits, atomically marks paid + advances
state via optimistic WHERE state='awaiting_eval_payment'; runs
AgentService.evaluateRequest, branches to awaiting_work_payment or rejected
- awaiting_work_payment: same pattern for work invoice, runs
AgentService.executeWork, advances to complete
- Any agent/LNbits error transitions job to failed
Demo router (artifacts/api-server/src/routes/demo.ts)
- GET /demo?request=...: in-memory rate limiter (5 req/hour per IP)
- Explicit guard for missing request param (coerce.string() workaround)
- Calls AgentService.executeWork directly, returns { result }
Dev router (artifacts/api-server/src/routes/dev.ts)
- POST /dev/stub/pay/:paymentHash: marks stub invoice paid in-memory
- Only mounted when NODE_ENV !== 'production'
Route index updated to mount all three routers
replit.md: documented full curl flow with all 6 steps, demo endpoint,
and dev stub-pay trigger
End-to-end verified with curl:
- Full flow: create → eval pay → evaluating → work pay → executing → complete
- Error cases: 400 on missing body/param, 404 on unknown job
2026-03-18 15:31:26 +00:00
|
|
|
- name: jobs
|
|
|
|
|
description: Payment-gated agent job operations
|
|
|
|
|
- name: demo
|
|
|
|
|
description: Free demo endpoint (rate-limited)
|
2026-03-13 23:21:55 +00:00
|
|
|
paths:
|
|
|
|
|
/healthz:
|
|
|
|
|
get:
|
|
|
|
|
operationId: healthCheck
|
|
|
|
|
tags: [health]
|
|
|
|
|
summary: Health check
|
|
|
|
|
description: Returns server health status
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: Healthy
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: "#/components/schemas/HealthStatus"
|
Task #3: MVP API — payment-gated jobs + demo endpoint
OpenAPI spec (lib/api-spec/openapi.yaml)
- Added POST /jobs, GET /jobs/{id}, GET /demo endpoints
- Added schemas: CreateJobRequest, CreateJobResponse, JobStatusResponse,
InvoiceInfo, JobState, DemoResponse, ErrorResponse
- Ran codegen: generated CreateJobBody, GetJobResponse, RunDemoQueryParams etc.
Jobs router (artifacts/api-server/src/routes/jobs.ts)
- POST /jobs: validates body, creates LNbits eval invoice, inserts job +
invoice in a DB transaction, returns { jobId, evalInvoice }
- GET /jobs/:id: fetches job, calls advanceJob() helper, returns state-
appropriate payload (eval/work invoice, reason, result, errorMessage)
- advanceJob() state machine:
- awaiting_eval_payment: checks LNbits, atomically marks paid + advances
state via optimistic WHERE state='awaiting_eval_payment'; runs
AgentService.evaluateRequest, branches to awaiting_work_payment or rejected
- awaiting_work_payment: same pattern for work invoice, runs
AgentService.executeWork, advances to complete
- Any agent/LNbits error transitions job to failed
Demo router (artifacts/api-server/src/routes/demo.ts)
- GET /demo?request=...: in-memory rate limiter (5 req/hour per IP)
- Explicit guard for missing request param (coerce.string() workaround)
- Calls AgentService.executeWork directly, returns { result }
Dev router (artifacts/api-server/src/routes/dev.ts)
- POST /dev/stub/pay/:paymentHash: marks stub invoice paid in-memory
- Only mounted when NODE_ENV !== 'production'
Route index updated to mount all three routers
replit.md: documented full curl flow with all 6 steps, demo endpoint,
and dev stub-pay trigger
End-to-end verified with curl:
- Full flow: create → eval pay → evaluating → work pay → executing → complete
- Error cases: 400 on missing body/param, 404 on unknown job
2026-03-18 15:31:26 +00:00
|
|
|
/jobs:
|
|
|
|
|
post:
|
|
|
|
|
operationId: createJob
|
|
|
|
|
tags: [jobs]
|
|
|
|
|
summary: Create a new agent job
|
|
|
|
|
description: Accepts a request, creates a job row, and issues an eval fee Lightning invoice.
|
|
|
|
|
requestBody:
|
|
|
|
|
required: true
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: "#/components/schemas/CreateJobRequest"
|
|
|
|
|
responses:
|
|
|
|
|
"201":
|
|
|
|
|
description: Job created successfully
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: "#/components/schemas/CreateJobResponse"
|
|
|
|
|
"400":
|
|
|
|
|
description: Invalid request body
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
|
"500":
|
|
|
|
|
description: Server error
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
|
/jobs/{id}:
|
|
|
|
|
get:
|
|
|
|
|
operationId: getJob
|
|
|
|
|
tags: [jobs]
|
|
|
|
|
summary: Get job status
|
|
|
|
|
description: Returns current job state. Automatically advances the state machine when a pending invoice is found to be paid.
|
|
|
|
|
parameters:
|
|
|
|
|
- name: id
|
|
|
|
|
in: path
|
|
|
|
|
required: true
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: Job status
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: "#/components/schemas/JobStatusResponse"
|
|
|
|
|
"404":
|
|
|
|
|
description: Job not found
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
|
"500":
|
|
|
|
|
description: Server error
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
|
/demo:
|
|
|
|
|
get:
|
|
|
|
|
operationId: runDemo
|
|
|
|
|
tags: [demo]
|
|
|
|
|
summary: Free demo (rate-limited)
|
|
|
|
|
description: Runs the agent without payment. Limited to 5 requests per IP per hour.
|
|
|
|
|
parameters:
|
|
|
|
|
- name: request
|
|
|
|
|
in: query
|
|
|
|
|
required: true
|
|
|
|
|
schema:
|
|
|
|
|
type: string
|
|
|
|
|
responses:
|
|
|
|
|
"200":
|
|
|
|
|
description: Demo result
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: "#/components/schemas/DemoResponse"
|
|
|
|
|
"400":
|
|
|
|
|
description: Missing or invalid request param
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
|
"429":
|
|
|
|
|
description: Rate limit exceeded
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
|
"500":
|
|
|
|
|
description: Server error
|
|
|
|
|
content:
|
|
|
|
|
application/json:
|
|
|
|
|
schema:
|
|
|
|
|
$ref: "#/components/schemas/ErrorResponse"
|
2026-03-13 23:21:55 +00:00
|
|
|
components:
|
|
|
|
|
schemas:
|
|
|
|
|
HealthStatus:
|
|
|
|
|
type: object
|
|
|
|
|
properties:
|
|
|
|
|
status:
|
|
|
|
|
type: string
|
|
|
|
|
required:
|
|
|
|
|
- status
|
Task #3: MVP API — payment-gated jobs + demo endpoint
OpenAPI spec (lib/api-spec/openapi.yaml)
- Added POST /jobs, GET /jobs/{id}, GET /demo endpoints
- Added schemas: CreateJobRequest, CreateJobResponse, JobStatusResponse,
InvoiceInfo, JobState, DemoResponse, ErrorResponse
- Ran codegen: generated CreateJobBody, GetJobResponse, RunDemoQueryParams etc.
Jobs router (artifacts/api-server/src/routes/jobs.ts)
- POST /jobs: validates body, creates LNbits eval invoice, inserts job +
invoice in a DB transaction, returns { jobId, evalInvoice }
- GET /jobs/:id: fetches job, calls advanceJob() helper, returns state-
appropriate payload (eval/work invoice, reason, result, errorMessage)
- advanceJob() state machine:
- awaiting_eval_payment: checks LNbits, atomically marks paid + advances
state via optimistic WHERE state='awaiting_eval_payment'; runs
AgentService.evaluateRequest, branches to awaiting_work_payment or rejected
- awaiting_work_payment: same pattern for work invoice, runs
AgentService.executeWork, advances to complete
- Any agent/LNbits error transitions job to failed
Demo router (artifacts/api-server/src/routes/demo.ts)
- GET /demo?request=...: in-memory rate limiter (5 req/hour per IP)
- Explicit guard for missing request param (coerce.string() workaround)
- Calls AgentService.executeWork directly, returns { result }
Dev router (artifacts/api-server/src/routes/dev.ts)
- POST /dev/stub/pay/:paymentHash: marks stub invoice paid in-memory
- Only mounted when NODE_ENV !== 'production'
Route index updated to mount all three routers
replit.md: documented full curl flow with all 6 steps, demo endpoint,
and dev stub-pay trigger
End-to-end verified with curl:
- Full flow: create → eval pay → evaluating → work pay → executing → complete
- Error cases: 400 on missing body/param, 404 on unknown job
2026-03-18 15:31:26 +00:00
|
|
|
ErrorResponse:
|
|
|
|
|
type: object
|
|
|
|
|
required:
|
|
|
|
|
- error
|
|
|
|
|
properties:
|
|
|
|
|
error:
|
|
|
|
|
type: string
|
|
|
|
|
InvoiceInfo:
|
|
|
|
|
type: object
|
|
|
|
|
required:
|
|
|
|
|
- paymentRequest
|
|
|
|
|
- amountSats
|
|
|
|
|
properties:
|
|
|
|
|
paymentRequest:
|
|
|
|
|
type: string
|
|
|
|
|
amountSats:
|
|
|
|
|
type: integer
|
|
|
|
|
CreateJobRequest:
|
|
|
|
|
type: object
|
|
|
|
|
required:
|
|
|
|
|
- request
|
|
|
|
|
properties:
|
|
|
|
|
request:
|
|
|
|
|
type: string
|
|
|
|
|
minLength: 1
|
|
|
|
|
CreateJobResponse:
|
|
|
|
|
type: object
|
|
|
|
|
required:
|
|
|
|
|
- jobId
|
|
|
|
|
- evalInvoice
|
|
|
|
|
properties:
|
|
|
|
|
jobId:
|
|
|
|
|
type: string
|
|
|
|
|
evalInvoice:
|
|
|
|
|
$ref: "#/components/schemas/InvoiceInfo"
|
|
|
|
|
JobState:
|
|
|
|
|
type: string
|
|
|
|
|
enum:
|
|
|
|
|
- awaiting_eval_payment
|
|
|
|
|
- evaluating
|
|
|
|
|
- rejected
|
|
|
|
|
- awaiting_work_payment
|
|
|
|
|
- executing
|
|
|
|
|
- complete
|
|
|
|
|
- failed
|
|
|
|
|
JobStatusResponse:
|
|
|
|
|
type: object
|
|
|
|
|
required:
|
|
|
|
|
- jobId
|
|
|
|
|
- state
|
|
|
|
|
properties:
|
|
|
|
|
jobId:
|
|
|
|
|
type: string
|
|
|
|
|
state:
|
|
|
|
|
$ref: "#/components/schemas/JobState"
|
|
|
|
|
evalInvoice:
|
|
|
|
|
$ref: "#/components/schemas/InvoiceInfo"
|
|
|
|
|
workInvoice:
|
|
|
|
|
$ref: "#/components/schemas/InvoiceInfo"
|
|
|
|
|
reason:
|
|
|
|
|
type: string
|
|
|
|
|
result:
|
|
|
|
|
type: string
|
|
|
|
|
errorMessage:
|
|
|
|
|
type: string
|
|
|
|
|
DemoResponse:
|
|
|
|
|
type: object
|
|
|
|
|
required:
|
|
|
|
|
- result
|
|
|
|
|
properties:
|
|
|
|
|
result:
|
|
|
|
|
type: string
|