Request. Agree.
Receive.

1 / Create your workspace

Use the customer portal or POST /v2/register with your name, email and consent. Use a random UUID v4 Idempotency-Key for registration retries. Save the returned access_key privately. Use a dedicated key for an agent customer.

Authorization: Bearer YOUR_SDS_ACCESS_KEY
Content-Type: application/json
Idempotency-Key: A_UNIQUE_REQUEST_KEY

Your email is a contact address; initial registration does not verify email ownership. Tokens are hashed in storage.

2 / Submit a request

POST /v2/projects
{
  "title": "Sales data assessment",
  "service": "data-quality",
  "brief": "Check missing fields and duplicate records for our operations team.",
  "input": {"rows": [{"customer":"A","amount":100}]}
}

HTTP 202 returns a project ID, status and Location resource. Reusing an Idempotency-Key with the same input returns the same project. Changed input returns 409.

3 / Accept the exact quote

GET /v2/projects/{id} returns the issued scope, terms, expiry, currency and amount_minor. The amount uses minor units: KES 1,500.00 is 150000.

POST /v2/projects/{id}/accept
{"quote_id":"THE_CURRENT_QUOTE_ID","accepted":true}

Your agent needs its owner's authority to accept the quote. Checkout returns a payment-provider URL when connected. Manual receipt verification also works. A browser redirect never counts as proof of payment.

4 / Receive the result

Poll GET /v2/projects/{id}. Once state is delivered, the response includes result and deliverables.

{
  "schema_version": "2.0",
  "id": "PROJECT_ID",
  "state": "delivered",
  "result": {"results": ["ROLE_RESULTS"]},
  "deliverables": [{
    "name": "report.json",
    "mime": "application/json",
    "sha256": "CONTENT_HASH",
    "url": "/v2/projects/PROJECT_ID/files/FILE_ID"
  }]
}

JSON supports direct automation. HTML supports reading and printing to PDF. Markdown supports editing and reuse. Data assessments include CSV field statistics. Engineering results include a ZIP and file manifest when implementation files are produced. File downloads require your bearer key.

Signed completion webhooks

Ask SDS to approve your HTTPS host, then POST /v2/webhook with url and a secret of at least 32 characters. SDS encrypts the signing secret at rest.

SDS-Event-ID: EVENT_ID
SDS-Signature: t=UNIX_SECONDS,v1=HEX_HMAC_SHA256

signature = HMAC_SHA256(secret, timestamp + "." + raw_body)

Validate the signature and timestamp, deduplicate by event_id, then fetch the authenticated result. Events contain tracking metadata, not raw project data. Failed delivery uses up to five attempts with backoff.

MCP tools

Connect your agent to this origin's /mcp endpoint with its customer bearer token. The server supports authenticated JSON-RPC POST.

• sds_list_services
• sds_create_project
• sds_get_project
• sds_list_projects
• sds_accept_quote
• sds_project_message

Tool requests enforce the same customer ownership, quote acceptance and release rules as the REST API.