esyURL Domain API
The domain API from esyURL — 2 operation(s) for domain.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/esyurl-fyi:esyurl-fyi-domain-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Esyurl Fyi Domain API
version: 2.0.0
contact:
name: esyURL
email: contact@esyurl.fyi
url: https://esyurl.fyi/about/contact
x-guidance: 'Get an API key first: follow /auth.md (agents sign themselves up, no human needed). Then POST /v1/links with {"targetUrl": "...", "slug": "..."} for a short link and GET /v1/links/{id}/qr for its QR code. PUT /v1/domain {"domain": "go.example.com"} sets a custom domain; for self-signed-up tenants it answers 402 and is paid with x402 (USDC), once per domain. The full guide is /llms.txt.'
description: 'Operations tagged domain across 2 of this provider''s published API definitions: openapi.json, esyurl-fyi-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://esyurl.fyi
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Domain
paths:
/v1/home:
get:
tags:
- Domain
summary: The link the root (/) of the tenant's custom domain shows
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
homeLinkId:
type:
- string
- 'null'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
WWW-Authenticate:
schema:
type: string
description: 'Bearer resource_metadata="{baseUrl}/.well-known/oauth-protected-resource" (RFC 9728; how to sign up: /auth.md)'
'403':
description: API key lacks the required scope
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: getV1Home
x-operation-id-source: derived
put:
tags:
- Domain
summary: Show this link at / of the tenant's custom domain (a link page becomes its home…
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- linkId
additionalProperties: false
properties:
linkId:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
homeLinkId:
type: string
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
WWW-Authenticate:
schema:
type: string
description: 'Bearer resource_metadata="{baseUrl}/.well-known/oauth-protected-resource" (RFC 9728; how to sign up: /auth.md)'
'403':
description: API key lacks the required scope
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not found (or not yours)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: putV1Home
x-operation-id-source: derived
delete:
tags:
- Domain
summary: 'Clear it: / of the custom domain answers 404 again'
responses:
'204':
description: Cleared
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
WWW-Authenticate:
schema:
type: string
description: 'Bearer resource_metadata="{baseUrl}/.well-known/oauth-protected-resource" (RFC 9728; how to sign up: /auth.md)'
'403':
description: API key lacks the required scope
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: deleteV1Home
x-operation-id-source: derived
servers:
- url: https://esyurl.fyi
/v1/domain:
get:
tags:
- Domain
summary: The tenant's alias domain, its status and the DNS records still to create
description: 'Requires `links:read`. Each call advances provisioning as far as it can: pending_validation → provisioning → pending_dns → active.'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
WWW-Authenticate:
schema:
type: string
description: 'Bearer resource_metadata="{baseUrl}/.well-known/oauth-protected-resource" (RFC 9728; how to sign up: /auth.md)'
'403':
description: API key lacks the required scope
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: getV1Domain
x-operation-id-source: derived
put:
tags:
- Domain
summary: Set (or replace) the alias domain, e.g. go.acme.com
x-payment-info:
price:
mode: fixed
currency: USD
amount: '5.00'
protocols:
- x402: {}
description: 'Requires `links:write`. Replacing an existing alias tears the old one down. For self-signed-up tenants (`tenant.origin` = `agent_signup`) a new domain is paid with x402 v2 (exact scheme, USDC): without a payment the answer is 402 with a PaymentRequired (body and base64 `PAYMENT-REQUIRED` header); repeat the request with the base64 PaymentPayload in `PAYMENT-SIGNATURE`. Validation and conflicts (400/409) come first and are never charged; re-setting the current domain is free. Operator tenants never pay.'
parameters:
- name: PAYMENT-SIGNATURE
in: header
schema:
type: string
description: Base64 x402 PaymentPayload (`X-PAYMENT` is accepted too)
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
properties:
domain:
type: string
example: go.acme.com
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
headers:
PAYMENT-RESPONSE:
schema:
type: string
description: Base64 x402 SettlementResponse, when this call was charged
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
WWW-Authenticate:
schema:
type: string
description: 'Bearer resource_metadata="{baseUrl}/.well-known/oauth-protected-resource" (RFC 9728; how to sign up: /auth.md)'
'402':
description: Payment required, or the payment failed
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequired'
headers:
PAYMENT-REQUIRED:
schema:
type: string
description: Base64 of the same PaymentRequired
PAYMENT-RESPONSE:
schema:
type: string
description: Base64 failed SettlementResponse, if settlement failed
'403':
description: API key lacks the required scope
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: The domain belongs to another tenant
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: '`payments_not_configured` (nothing charged; retry later) or `service_unavailable` (facilitator down)'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: putV1Domain
x-operation-id-source: derived
delete:
tags:
- Domain
summary: Remove the alias domain
description: Requires `links:write`.
responses:
'204':
description: Removed
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
WWW-Authenticate:
schema:
type: string
description: 'Bearer resource_metadata="{baseUrl}/.well-known/oauth-protected-resource" (RFC 9728; how to sign up: /auth.md)'
'403':
description: API key lacks the required scope
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: deleteV1Domain
x-operation-id-source: derived
servers:
- url: https://esyurl.fyi
components:
schemas:
Domain:
type: object
properties:
domain:
type:
- string
- 'null'
status:
type: string
enum:
- none
- pending_validation
- provisioning
- pending_dns
- active
- failed
url:
type: string
description: https://{domain}, once active
target:
type: string
description: What your domain must CNAME to
dnsRecords:
type: array
items:
type: object
properties:
purpose:
type: string
name:
type: string
type:
type: string
value:
type: string
done:
type: boolean
instructions:
type: string
lastError:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- bad_request
- validation_error
- unauthorized
- forbidden
- not_found
- conflict
- gone
- payment_required
- quota_exceeded
- rate_limited
- internal_error
- payments_not_configured
- service_unavailable
message:
type: string
details: {}
PaymentRequired:
type: object
description: x402 v2 PaymentRequired
required:
- x402Version
- resource
- accepts
properties:
x402Version:
const: 2
error:
type: string
resource:
type: object
properties:
url:
type: string
description:
type: string
mimeType:
type: string
accepts:
type: array
items:
type: object
properties:
scheme:
const: exact
network:
type: string
example: eip155:8453
amount:
type: string
description: Atomic units (USDC has 6 decimals)
example: '5000000'
asset:
type: string
description: USDC contract address
payTo:
type: string
maxTimeoutSeconds:
type: integer
extra:
type: object
description: 'EIP-712 domain of the token: name, version'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key `esy_{keyId}_{secret}`, from an operator or from agent self-sign-up (/auth.md)
apiKeyHeader:
type: apiKey
in: header
name: x-api-key
x-refined-from:
- openapi.json
- esyurl-fyi-openapi.json