{ "openapi": "3.1.0", "info": { "title": "dorepal API", "version": "0.3.0", "description": "Quote, pay and track cross-border goods, services and paid work through dorepal. Agents pay quoted amounts with Stripe shared payment tokens (Link agent wallet) or a Stripe payment method token. Funds are released to the maker only after the user accepts delivery. Studios, creators and merchants (or their agents) register supply listings; the public board (/v1/board, mirrored to https://github.com/brucehuang1/dorepal-board) lists scrubbed demand and supply for discovery — every deal still runs through dorepal. Same operations are available as MCP tools at https://dorepal.com/mcp. The email/web intake endpoint /api/request is kept for agents without wallets.", "contact": { "email": "hello@dorepal.com", "url": "https://dorepal.com" }, "termsOfService": "https://dorepal.com/terms" }, "servers": [ { "url": "https://dorepal.com" } ], "paths": { "/v1/health": { "get": { "operationId": "health", "summary": "Service status", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "stripe_connected": { "type": "boolean" }, "profile_configured": { "type": "boolean" } } } } } } } } }, "/v1/offers": { "get": { "operationId": "listOffers", "summary": "Catalog with USD prices", "responses": { "200": { "description": "Offers", "content": { "application/json": { "schema": { "type": "object", "properties": { "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } } } } } } } } } }, "/v1/quotes": { "post": { "operationId": "createQuote", "summary": "Create a quote request (instant for per-unit offers, otherwise a human quote within 24h)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuote" } } } }, "responses": { "201": { "description": "Quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/quotes/{quote_id}": { "get": { "operationId": "getQuote", "summary": "Quote / order status", "parameters": [ { "$ref": "#/components/parameters/quote_id" } ], "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "404": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "modifyQuote", "summary": "Change an unpaid quote", "parameters": [ { "$ref": "#/components/parameters/quote_id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1 }, "deadline": { "type": "string" }, "budget_usd": { "type": "number" }, "delivery_address": { "type": "string" }, "need_append": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "private" ] } } } } } }, "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "409": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "cancelQuote", "summary": "Cancel an unpaid quote", "parameters": [ { "$ref": "#/components/parameters/quote_id" }, { "name": "reason", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "409": { "$ref": "#/components/responses/Error" } } } }, "/v1/quotes/by-ref/{ref}": { "get": { "operationId": "getQuoteByRef", "summary": "Look up by DP- reference: full quote with the buyer email, otherwise the public board entry", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^DP-[A-Z2-9]{6}$" } }, { "name": "email", "in": "query", "schema": { "type": "string", "format": "email" }, "description": "Buyer email as given at creation" } ], "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Quote" }, { "$ref": "#/components/schemas/BoardDemand" } ] } } } }, "404": { "$ref": "#/components/responses/Error" } }, "description": "Refs appear on the public board, so the full record needs ?email= matching the buyer; without it only the sanitized board entry is returned (404 if the quote is private or closed). Search may lag ~1 min after creation." } }, "/v1/quotes/{quote_id}/complete": { "post": { "operationId": "completePayment", "summary": "Pay the quoted amount with an agent-wallet credential", "description": "Only when status is \"quoted\". Send a Stripe shared payment token (spt_…) issued for exactly `amount` and scoped to dorepal's business_profile, or a Stripe payment method token (pm_…). Idempotent per credential; Idempotency-Key header honored.", "parameters": [ { "$ref": "#/components/parameters/quote_id" }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletePayment" } } } }, "responses": { "200": { "description": "Paid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResult" } } } }, "402": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "410": { "$ref": "#/components/responses/Error" } } } }, "/api/request": { "post": { "summary": "Submit a quote request or supplier profile", "operationId": "submitRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mode", "need", "email" ], "properties": { "mode": { "type": "string", "enum": [ "need", "earn" ], "description": "need = request a quote (buyer); earn = register as supplier" }, "need": { "type": "string", "description": "What you need, or what you can do" }, "budget": { "type": "string", "description": "Budget and deadline (buyers) or payout method (suppliers)" }, "email": { "type": "string", "format": "email" }, "lang": { "type": "string", "enum": [ "en", "zh", "pt" ] } } } } } }, "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "ref": { "type": "string" }, "next": { "type": "string" } } } } } } } } }, "/v1/board": { "get": { "operationId": "board", "summary": "Public board: demand + supply (discovery only)", "description": "PII-scrubbed demand (quote requests) and supply (listings) with refs DP-/SP-, dorepal catalog and how to act. No contact details, no quoted amounts, no ids — every deal, escrow payment and settlement runs through dorepal. Cached ~5 min; mirrored every 15 min to https://github.com/brucehuang1/dorepal-board. Works before Stripe is connected (catalog only).", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "custom_goods", "photo_retouching", "translation", "subtitles", "slides", "company_tasks", "hackathon", "other" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "demand: open, quoted, in_progress, done, expired · supply: listed, paused" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Board", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } } } } }, "/v1/board/demand": { "get": { "operationId": "boardDemand", "summary": "Public demand only", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "custom_goods", "photo_retouching", "translation", "subtitles", "slides", "company_tasks", "hackathon", "other" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "demand: open, quoted, in_progress, done, expired · supply: listed, paused" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Board", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } } } } }, "/v1/board/supply": { "get": { "operationId": "boardSupply", "summary": "Public supply listings only", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "custom_goods", "photo_retouching", "translation", "subtitles", "slides", "company_tasks", "hackathon", "other" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "demand: open, quoted, in_progress, done, expired · supply: listed, paused" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Board", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } } } } }, "/v1/supply": { "post": { "operationId": "registerSupply", "summary": "Register a supply listing (studios, creators, merchants, their agents)", "description": "The listing (ref SP-XXXXXX) is published on the board and its GitHub mirror immediately and marked verified after dorepal checks it. Email, portfolio and payout details are never published; buyers order through dorepal. Pass demand_ref to respond to a demand. Keep supply_id to update or remove the listing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterSupply" } } } }, "responses": { "201": { "description": "Listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supply" } } } }, "400": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/supply/{supply_id}": { "get": { "operationId": "getSupply", "summary": "Full listing record (by supply_id)", "parameters": [ { "$ref": "#/components/parameters/supply_id" } ], "responses": { "200": { "description": "Listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supply" } } } }, "404": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateSupply", "summary": "Update, pause or remove a listing", "parameters": [ { "$ref": "#/components/parameters/supply_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSupply" } } } }, "responses": { "200": { "description": "Listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supply" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "removeSupply", "summary": "Remove a listing (same as status removed)", "parameters": [ { "$ref": "#/components/parameters/supply_id" } ], "responses": { "200": { "description": "Listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supply" } } } }, "404": { "$ref": "#/components/responses/Error" } } } } }, "components": { "parameters": { "quote_id": { "name": "quote_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cus_[A-Za-z0-9]+$" }, "description": "quote_id returned by createQuote" }, "supply_id": { "name": "supply_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cus_[A-Za-z0-9]+$" }, "description": "supply_id returned by registerSupply" } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "schemas": { "Offer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "unit": { "type": "string" }, "pricing": { "type": "object" }, "lead_time_days": { "type": "array", "items": { "type": "integer" } }, "deliverable": { "type": "string" } } }, "CreateQuote": { "type": "object", "required": [ "need", "email" ], "properties": { "need": { "type": "string", "minLength": 10, "maxLength": 1900, "description": "What the user needs, in their words. A scrubbed summary is published on the board unless visibility is private — keep personal names and addresses in principal_name / delivery_address, not here" }, "email": { "type": "string", "format": "email", "description": "Email of the person the agent acts for" }, "offer_id": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "budget_usd": { "type": "number" }, "deadline": { "type": "string" }, "delivery_country": { "type": "string", "minLength": 2, "maxLength": 2 }, "delivery_address": { "type": "string" }, "principal_name": { "type": "string" }, "agent": { "type": "string", "description": "e.g. Muse, Claude, ChatGPT" }, "agent_platform": { "type": "string" }, "supply_ref": { "type": "string", "pattern": "^SP-[A-Z2-9]{6}$", "description": "Buy from a specific board listing" }, "visibility": { "type": "string", "enum": [ "public", "private" ], "default": "public", "description": "public: a scrubbed summary of the need (no name, email, address) is listed on the public board; private: not listed" } } }, "Quote": { "type": "object", "properties": { "quote_id": { "type": "string" }, "ref": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_quote", "quoted", "paid", "expired", "cancelled" ] }, "amount": { "type": [ "integer", "null" ], "description": "USD cents" }, "currency": { "type": [ "string", "null" ] }, "amount_display": { "type": [ "string", "null" ] }, "quote_note": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "payment": { "type": [ "object", "null" ], "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" }, "handlers": { "type": "array", "items": { "type": "object" } }, "complete_endpoint": { "type": "string" }, "hosted_checkout": { "type": "object" } } }, "order": { "type": [ "object", "null" ] }, "next_step": { "type": [ "string", "null" ] }, "links": { "type": "object" }, "supply_ref": { "type": [ "string", "null" ] }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "board": { "type": [ "object", "null" ], "description": "Board + GitHub mirror links when the quote is listed" } } }, "CompletePayment": { "type": "object", "properties": { "credential": { "type": "object", "required": [ "type", "token" ], "properties": { "type": { "type": "string", "enum": [ "shared_payment_token", "stripe_payment_token", "stripe_payment_method" ] }, "token": { "type": "string" } } }, "idempotency_key": { "type": "string" } } }, "PaymentResult": { "type": "object", "properties": { "order": { "type": "object" }, "payment": { "type": "object", "properties": { "status": { "type": "string" }, "transaction_id": { "type": "string" }, "amount": { "type": "integer" }, "currency": { "type": "string" } } }, "quote": { "$ref": "#/components/schemas/Quote" } } }, "RegisterSupply": { "type": "object", "required": [ "title", "description", "categories", "email" ], "properties": { "title": { "type": "string", "minLength": 4, "maxLength": 80 }, "description": { "type": "string", "minLength": 20, "maxLength": 1500, "description": "Skills, samples, turnaround, what you need from the buyer" }, "categories": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "enum": [ "custom_goods", "photo_retouching", "translation", "subtitles", "slides", "company_tasks", "hackathon", "other" ] } }, "supplier_type": { "type": "string", "enum": [ "studio", "creator", "merchant", "individual", "agent" ], "default": "studio" }, "display_name": { "type": "string", "maxLength": 60, "description": "Public handle or brand (consent to publish); omit to stay anonymous" }, "price_note": { "type": "string", "maxLength": 160 }, "price_from_usd": { "type": "number", "minimum": 0 }, "lead_time_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "capacity": { "type": "string", "maxLength": 120 }, "regions": { "type": "string", "maxLength": 120 }, "languages": { "type": "string", "maxLength": 80 }, "portfolio_url": { "type": "string", "format": "uri", "description": "Kept private; used for vetting" }, "payout_rail": { "type": "string", "enum": [ "alipay", "pix", "m_pesa", "bank", "stripe", "wise", "other" ], "description": "Kept private" }, "demand_ref": { "type": "string", "pattern": "^DP-[A-Z2-9]{6}$", "description": "Respond to a demand on the board" }, "agent": { "type": "string", "maxLength": 80 }, "agent_platform": { "type": "string", "maxLength": 40 }, "email": { "type": "string", "format": "email", "description": "Contact email for dorepal (never published)" } } }, "UpdateSupply": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "listed", "paused", "removed" ] }, "title": { "type": "string", "minLength": 4, "maxLength": 80 }, "description": { "type": "string", "minLength": 20, "maxLength": 1500, "description": "Skills, samples, turnaround, what you need from the buyer" }, "categories": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "enum": [ "custom_goods", "photo_retouching", "translation", "subtitles", "slides", "company_tasks", "hackathon", "other" ] } }, "supplier_type": { "type": "string", "enum": [ "studio", "creator", "merchant", "individual", "agent" ], "default": "studio" }, "display_name": { "type": "string", "maxLength": 60, "description": "Public handle or brand (consent to publish); omit to stay anonymous" }, "price_note": { "type": "string", "maxLength": 160 }, "price_from_usd": { "type": "number", "minimum": 0 }, "lead_time_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "capacity": { "type": "string", "maxLength": 120 }, "regions": { "type": "string", "maxLength": 120 }, "languages": { "type": "string", "maxLength": 80 }, "portfolio_url": { "type": "string", "format": "uri", "description": "Kept private; used for vetting" }, "payout_rail": { "type": "string", "enum": [ "alipay", "pix", "m_pesa", "bank", "stripe", "wise", "other" ], "description": "Kept private" }, "demand_ref": { "type": "string", "pattern": "^DP-[A-Z2-9]{6}$", "description": "Respond to a demand on the board" }, "agent": { "type": "string", "maxLength": 80 }, "agent_platform": { "type": "string", "maxLength": 40 } } }, "BoardDemand": { "type": "object", "properties": { "ref": { "type": "string", "pattern": "^DP-[A-Z2-9]{6}$" }, "side": { "type": "string", "const": "demand" }, "status": { "type": "string", "enum": [ "open", "quoted", "in_progress", "done", "expired" ] }, "category": { "type": "string" }, "category_name": { "type": "string" }, "summary": { "type": "string", "description": "Scrubbed need, ≤300 chars" }, "quantity": { "type": [ "integer", "null" ] }, "unit": { "type": [ "string", "null" ] }, "budget_usd": { "type": [ "number", "null" ] }, "deadline": { "type": [ "string", "null" ] }, "delivery_country": { "type": [ "string", "null" ] }, "supply_ref": { "type": [ "string", "null" ] }, "agent": { "type": [ "string", "null" ] }, "responses": { "type": "integer", "description": "Supply listings responding to this demand" }, "created_at": { "type": "string", "format": "date-time" }, "act": { "type": "object" } } }, "BoardSupply": { "type": "object", "properties": { "ref": { "type": "string", "pattern": "^SP-[A-Z2-9]{6}$" }, "side": { "type": "string", "const": "supply" }, "status": { "type": "string", "enum": [ "listed", "paused" ] }, "verified": { "type": "boolean" }, "display_name": { "type": "string" }, "supplier_type": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" }, "summary": { "type": "string" }, "price_note": { "type": [ "string", "null" ] }, "price_from_usd": { "type": [ "number", "null" ] }, "lead_time_days": { "type": [ "integer", "null" ] }, "capacity": { "type": [ "string", "null" ] }, "regions": { "type": [ "string", "null" ] }, "languages": { "type": [ "string", "null" ] }, "demand_ref": { "type": [ "string", "null" ] }, "agent": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "act": { "type": "object" } } }, "Board": { "type": "object", "properties": { "updated_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "github": { "type": "string" }, "stripe_connected": { "type": "boolean" }, "act": { "type": "object" }, "rules": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "catalog": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "demand": { "type": "array", "items": { "$ref": "#/components/schemas/BoardDemand" } }, "supply": { "type": "array", "items": { "$ref": "#/components/schemas/BoardSupply" } } } }, "Supply": { "type": "object", "description": "Full listing: the BoardSupply fields plus private ones, returned only to the agent holding supply_id", "allOf": [ { "$ref": "#/components/schemas/BoardSupply" }, { "type": "object", "properties": { "supply_id": { "type": "string" }, "status": { "type": "string", "enum": [ "listed", "paused", "removed" ] }, "description": { "type": "string" }, "email": { "type": "string" }, "portfolio_url": { "type": [ "string", "null" ] }, "payout_rail": { "type": [ "string", "null" ] }, "agent_platform": { "type": [ "string", "null" ] }, "board": { "type": [ "object", "null" ] }, "next_step": { "type": "string" }, "links": { "type": "object" } } } ] } } } }