Project domains

Connect a custom domain

Connects a custom domain to the project: creates or replaces its desired ProjectDomain state for web hosting, email sending, email receiving, and custom mailbox addresses. The domain rides in the body; the same call on a connected domain replaces its desired state. The response separates desired, observed, and effective state and returns checks, DNS records, authority options, and canonical next_actions.

post/projects/v1/{project_id}/domains

Request

  • Base URL: https://api.run402.com
  • URL: https://api.run402.com/projects/v1/{project_id}/domains
  • Auth: one of:
    • API key in header SIGN-IN-WITH-X
    • HTTP bearer
    • HTTP bearer

Path parameters

project_idstring required

Run402 project ID. Public IDs are not UUIDs.

Example:prj_1741340000_0042

Target project id. Authorization is checked server-side through wallet SIWX, control-plane session, or scoped grant key.

Headers

SIGN-IN-WITH-Xstring required

SIWX auth header — base64-encoded JSON payload containing a signed CAIP-122 (EIP-4361) message. See https://docs.x402.org/extensions/sign-in-with-x.

Request body

domainstring required

Lowercase DNS name to connect to the project.

Example request

{
  "domain": "kysigned.com",
  "desired": {
    "web": {
      "target": "production"
    }
  }
}

Response

Custom domain connected

project_idstring required

Run402 project ID. Public IDs are not UUIDs.

domainstring required
status'action_required' | 'waiting' | 'active' | 'needs_repair' | 'failed' required
created_atstring date-time
updated_atstring date-time

Example response

{
  "project_id": "prj_1741340000_0042",
  "domain": "kysigned.com",
  "desired": {
    "web": {
      "target": "production"
    }
  },
  "next_actions": [
    {
      "method": "POST",
      "path": "/tiers/v1/hobby",
      "auth": "x402"
    }
  ],
  "next_action": {
    "method": "POST",
    "path": "/tiers/v1/hobby",
    "auth": "x402"
  },
  "alternate_actions": [
    {
      "method": "POST",
      "path": "/tiers/v1/hobby",
      "auth": "x402"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.