# Slipdock

Infrastructure for AI agents: domains, DNS, TLS. You (an AI agent) can use this
API directly. There is no signup form and no browser step for you.

## The one thing to understand

You can do everything except move money. When something costs money we email the
human who owns the workspace a payment link. You poll the order until it flips
to `complete`. If they have funded a wallet and set a cap, purchases inside that
cap complete immediately with no email.

A 402 is not a failure. It is the normal first-purchase path. Tell your user
"I've emailed you a link to approve $X" and keep polling.

## Start

    POST https://api.slipdock.ai/v1/workspaces
    {"owner_email": "the-human@example.com", "label": "optional"}
    → {"workspace_id": "ws_…", "token": "sk_live_…"}

Store the token. Send it as `Authorization: Bearer <token>`.

## What you get for free, immediately

No payment, no human, no waiting:

  · a **private git repository** — POST /v1/repos
  · a **static site** on it
  · **authoritative DNS** for any domain in this workspace
  · unlimited domain availability searches

## Shipping code: push it, don't build it

You do not need Docker, a registry, or a container image. Claim a repo, push
your source, and Slipdock builds and deploys it.

    POST /v1/repos {"name": "my-app"}
    → {"clone_url": "…", "push": {"commands": [...]}}

    git init -b main && git add -A && git commit -m "initial"
    git remote add slipdock https://ws_abc:$SLIPDOCK_TOKEN@git.slipdock.ai/…
    git push -u slipdock main

Use your API token as the git password and the workspace id as the username —
the same credential as the REST API. The repo is **private** and it is a plain
git remote: clone it and take it elsewhere whenever you want.

## Plans and limits

The free plan is metered and **enforced, not billed** — hit the cap and the app
throttles rather than generating a surprise bill for your user. `GET /v1/plan`
returns usage, limits and what to do when you are near them. Upgrading asks the
human, like any other spend.

## Endpoints

    POST /v1/repos             {"name":"my-app"}   free private git repo
    GET  /v1/repos                                   repos + latest commit
    GET  /v1/plan                                    quota usage + limits
    GET  /v1/subscriptions                           recurring services, runway
    GET  /v1/domains/search?q=name&tlds=com,dev,io   availability + price
    POST /v1/domains/register  {"domain":"x.com","years":1}
    GET  /v1/domains                                 what this workspace owns
    GET  /v1/orders/{id}                             poll an order
    GET  /v1/wallet                                  balance, cap, ledger
    POST /v1/wallet/topup      {"amount_cents":5000} asks the human
    GET  /v1/events                                  audit timeline
    GET  /v1/workspaces/me

Full schema: https://api.slipdock.ai/openapi.json

## Errors tell you what to do next

Every error carries `next_action`:

    {"error":"payment_required",
     "message":"…",
     "next_action":{"type":"await_payment","poll":"/v1/orders/o_123",
                    "pay_link_sent_to":"o***@example.com"}}

`type` is one of: await_payment · retry · retry_with · search_alternatives ·
create_workspace · await_owner · contact_support · upgrade_plan ·
request_topup · overage_billed · done.

## Watch the runway, unprompted

Responses carry `runway_days` once the workspace has anything recurring. If it
drops below 30, tell your user before they find out the hard way — "your site
stops in about 11 days unless you add credit" is the kind of thing they hired
you for.

## Idempotency

Send `Idempotency-Key` on any POST. Repeating a register call with the same key
returns the same order instead of buying twice. Registration defaults to keying
on the domain name, so an accidental retry is always safe.

## Manners

Search is cached and cheap; don't loop it hundreds of times — upstream
registries rate-limit us and we pass that on. Poll orders every 2-5s, not
faster. Prices are wholesale plus a flat markup, and renewals cost the same as
registration — you can quote your user confidently.