{ "openapi": "3.0.0", "info": { "title": "Dealer Node API", "description": "API for container deployment with x402 payment protocol", "version": "2.0" }, "servers": [ { "url": "https://backend.dealernode.app/api", "description": "Production" } ], "paths": { "/v2/jobs/quote": { "post": { "operationId": "JobsV2Controller_createQuote", "summary": "Create a deployment quote", "description": "Submits a Docker image for analysis and creates a quote job. Returns a `job_id` to check the quote status with GET /v2/jobs/quote/{id}.\n\n**Flow:**\n1. Submit image name and duration\n2. Receive `job_id` in response\n3. Poll GET /v2/jobs/quote/{id} until `status: 'ready'`\n4. Use the `job_id` as `quote_id` in POST /v2/jobs", "tags": [ "Jobs" ], "security": [ { "api-key": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image_name", "duration_seconds" ], "properties": { "image_name": { "type": "string", "example": "nginx:latest", "description": "Docker image to deploy" }, "duration_seconds": { "type": "number", "example": 3600, "description": "Duration in seconds" } } } } } }, "responses": { "201": { "description": "Quote job created", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Job ID to check status and use as quote_id in deploy", "example": "cmiz58n390004tmmkaz3d8taf" }, "message": { "type": "string", "example": "Quote created. Use GET /v2/jobs/quote/:id to check status." } } } } } }, "400": { "description": "Invalid request parameters" } } } }, "/v2/jobs/quote/{id}": { "get": { "operationId": "JobsV2Controller_getQuoteStatus", "summary": "Get quote status", "description": "Check the status of a quote by job_id. Returns `pending` while analyzing or `ready` with full pricing details.\n\n**Pending Response:**\n- `status: 'pending'` - analysis in progress\n- `retry_after_seconds: 60` - suggested retry interval\n\n**Ready Response:**\n- `status: 'ready'` - analysis complete\n- `quote` - pricing details\n- `machine` - CPU and memory specs\n- `x402` - payment requirements", "tags": [ "Jobs" ], "security": [ { "api-key": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job ID from POST /v2/jobs/quote", "schema": { "type": "string" }, "example": "cmiz58n390004tmmkaz3d8taf" } ], "responses": { "200": { "description": "Quote status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "pending" ], "example": "ready" }, "job_id": { "type": "string", "description": "Job ID to use as quote_id in POST /v2/jobs", "example": "cmiz58n390004tmmkaz3d8taf" }, "retry_after_seconds": { "type": "number", "description": "Only when status is pending", "example": 3 }, "quote": { "type": "object", "description": "Only when status is ready", "properties": { "image_name": { "type": "string", "example": "nginx:latest" }, "duration_seconds": { "type": "number", "example": 3600 }, "price_usd": { "type": "number", "example": 2.50 }, "currency": { "type": "string", "example": "USDC" }, "network": { "type": "string", "example": "base" } } }, "machine": { "type": "object", "description": "Only when status is ready", "properties": { "cpu": { "type": "number", "description": "Number of CPU cores", "example": 1 }, "memory_mb": { "type": "number", "description": "Memory in megabytes", "example": 256 } } }, "x402": { "type": "object", "description": "Only when status is ready - x402 payment requirements", "properties": { "scheme": { "type": "string", "example": "exact" }, "network": { "type": "string", "example": "base" }, "asset": { "type": "string", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "amount": { "type": "string", "description": "Amount in token decimals (USDC has 6 decimals)", "example": "2500000" }, "payTo": { "type": "string", "description": "Wallet address to send payment to" }, "facilitator": { "type": "string", "example": "https://x402.org/facilitator" } } } } } } } }, "404": { "description": "Quote not found" } } } }, "/v2/jobs": { "post": { "operationId": "JobsV2Controller_createJob", "summary": "Create a deployment job", "description": "Creates and starts a container deployment. Requires payment via the x402 protocol.\n\n**Payment Flow:**\n1. Call this endpoint without `X-PAYMENT` header to receive 402 response with payment requirements\n2. Sign an EIP-3009 `transferWithAuthorization` for USDC on Base network\n3. Retry with `X-PAYMENT` header containing the Base64-encoded signed payload\n4. Upon successful payment verification, the container is deployed\n\n**Tip:** Include `quote_id` from a previous quote request to ensure price consistency.", "tags": [ "Jobs" ], "security": [ { "api-key": [] } ], "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "description": "x402 payment payload (Base64 encoded JSON with EIP-3009 signature)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quote_id" ], "properties": { "quote_id": { "type": "string", "example": "cmiywzeps0002tms8r6tr2xma", "description": "Job ID from POST /v2/jobs/quote (image_name and duration are pulled from the quote)" }, "env": { "type": "object", "example": { "NODE_ENV": "production" }, "description": "Environment variables (optional)" } } } } } }, "responses": { "201": { "description": "Job created successfully", "headers": { "X-PAYMENT-RESPONSE": { "description": "Base64 encoded JSON with transaction details", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } }, "402": { "description": "Payment required - includes x402 payment requirements", "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "number", "example": 1 }, "accepts": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRequirement" } }, "error": { "type": "string" } } } } } }, "400": { "description": "Invalid request or image not analyzed" } } } }, "/v2/jobs/{id}": { "get": { "operationId": "JobsV2Controller_getJob", "summary": "Get job status and details", "description": "Retrieves the current status and details of a deployment job. Use this endpoint to monitor progress after creating a deployment.\n\n**Status Values:**\n- `QUEUED`: Job is waiting to be processed\n- `ANALYZING`: Image is being analyzed for resource requirements\n- `DEPLOYING`: Container is being provisioned\n- `RUNNING`: Container is active and running\n- `FAILED`: Deployment failed (check logs for details)\n- `COMPLETED`: Job finished successfully\n\n**Polling:** For deployments, poll every 5-10 seconds until status is RUNNING or FAILED.", "tags": [ "Jobs" ], "security": [ { "api-key": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "imageName": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Job not found" } } } }, "/v2/jobs/{id}/logs": { "get": { "operationId": "JobsV2Controller_getLogs", "summary": "Get container logs", "description": "Retrieves stdout/stderr output from a running or completed container. Useful for debugging deployment issues or monitoring application output.\n\n**Availability:**\n- Logs are only available after the container starts running\n- Returns 404 if the job hasn't started yet or logs are unavailable\n- Logs are retained for 24 hours after container stops\n\n**Tip:** Poll this endpoint periodically to stream live output from your container.", "tags": [ "Jobs" ], "security": [ { "api-key": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Logs retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "string" } } } } } }, "404": { "description": "Job or logs not found" } } } }, "/v2/jobs/{id}/machine": { "get": { "operationId": "JobsV2Controller_getMachineInfo", "summary": "Get machine info", "description": "Retrieves machine information for a running deployment including hostname, IP address, exposed ports, and remaining execution time.\n\n**Use cases:**\n- Get the public URL to access your deployed service\n- Monitor remaining runtime before automatic shutdown\n- Verify which ports are exposed\n\n**Note:** Returns null values for machine info if the container hasn't started yet.", "tags": [ "Jobs" ], "security": [ { "api-key": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job ID from POST /v2/jobs", "schema": { "type": "string" }, "example": "cmiz58n390004tmmkaz3d8taf" } ], "responses": { "200": { "description": "Machine information", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "example": "cmiz58n390004tmmkaz3d8taf" }, "status": { "type": "string", "enum": [ "pending", "starting", "running", "completed", "failed" ], "example": "running" }, "machine": { "type": "object", "nullable": true, "properties": { "machine_id": { "type": "string", "example": "d8d9799a619d78" }, "hostname": { "type": "string", "example": "app-02a5bbbc.fly.dev", "description": "Fly.io hostname for accessing the service" }, "ip": { "type": "string", "nullable": true, "example": "123.45.67.89", "description": "IPv4 address if allocated" }, "ports": { "type": "array", "items": { "type": "number" }, "example": [ 80, 443 ], "description": "Exposed TCP ports" } } }, "timing": { "type": "object", "nullable": true, "properties": { "started_at": { "type": "string", "format": "date-time", "example": "2025-12-10T17:33:50Z" }, "estimated_end_at": { "type": "string", "format": "date-time", "example": "2025-12-10T18:33:50Z" }, "remaining_seconds": { "type": "number", "example": 3420, "description": "Seconds until deployment expires" } } }, "resources": { "type": "object", "properties": { "cpu": { "type": "number", "example": 1 }, "memory_mb": { "type": "number", "example": 256 } } } } } } } }, "404": { "description": "Job not found" } } } } }, "components": { "securitySchemes": { "api-key": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API Key for external integrations. Generate via dashboard after staking 250K DNODE tokens." } }, "schemas": { "PaymentRequirement": { "type": "object", "properties": { "scheme": { "type": "string", "example": "exact" }, "network": { "type": "string", "example": "base" }, "maxAmountRequired": { "type": "string", "example": "2500000" }, "resource": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "number" }, "asset": { "type": "string", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "extra": { "type": "object", "properties": { "name": { "type": "string", "example": "USD Coin" }, "version": { "type": "string", "example": "2" } } } } } } } }