esyURL Public API
The public API from esyURL — 7 operation(s) for public.
Operations 8
GET
/{slug}/i/{imageId}.png
A picture on a link page (avatar, thumbnail, background); immutable, cached for…
#
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-public-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 Public 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 public 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: Public
paths:
/health:
get:
tags:
- Public
summary: Liveness check
security: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
ok:
const: true
operationId: getHealth
x-operation-id-source: derived
servers:
- url: https://esyurl.fyi
/{slug}:
get:
tags:
- Public
summary: 'Short URL: a redirect, or a link page'
description: What `shortUrl` points at. Slugs never collide with the other root routes (those names are reserved).
security: []
parameters:
- name: slug
in: path
required: true
schema:
$ref: '#/components/schemas/Slug'
- name: s
in: query
schema:
type: string
enum:
- qr
description: '`qr` marks the visit as a QR scan (QR images encode it); otherwise the visit is `direct`'
responses:
'200':
description: 'A link page (no rule matched): one HTML document, no script, a strict Content-Security-Policy. GET records a visit; HEAD does not.'
content:
text/html:
schema:
type: string
'302':
description: Redirect to targetUrl, or the matching rule's (query string not forwarded). GET records a visit; HEAD does not.
headers:
Location:
schema:
type: string
'404':
description: Unknown slug, or not served on this host
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'410':
description: Link is paused
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: getBySlug
x-operation-id-source: derived
servers:
- url: https://esyurl.fyi
/{slug}/{itemId}:
get:
tags:
- Public
summary: 'A link page''s button: counts a human click, then redirects to its url'
security: []
parameters:
- name: slug
in: path
required: true
schema:
$ref: '#/components/schemas/Slug'
- name: itemId
in: path
required: true
schema:
type: string
responses:
'302':
description: To the item's url
headers:
Location:
schema:
type: string
'404':
description: Unknown link or button, or a disabled one
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'410':
description: Link is paused
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: getBySlugByItemId
x-operation-id-source: derived
servers:
- url: https://esyurl.fyi
/{slug}/i/{imageId}.png:
get:
tags:
- Public
summary: A picture on a link page (avatar, thumbnail, background); immutable, cached for…
security: []
parameters:
- name: slug
in: path
required: true
schema:
$ref: '#/components/schemas/Slug'
- name: imageId
in: path
required: true
schema:
type: string
responses:
'200':
description: PNG
content:
image/png:
schema:
type: string
format: binary
'404':
description: Unknown picture
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: getBySlugI{imageId}Png
x-operation-id-source: derived
servers:
- url: https://esyurl.fyi
/r/{slug}:
get:
tags:
- Public
summary: Short URL redirect (original form, kept as a permanent alias of `/{slug}`)
security: []
parameters:
- name: slug
in: path
required: true
schema:
$ref: '#/components/schemas/Slug'
- name: s
in: query
schema:
type: string
enum:
- qr
description: '`qr` marks the visit as a QR scan (QR images encode it); otherwise the visit is `direct`'
responses:
'200':
description: 'A link page (no rule matched): one HTML document, no script, a strict Content-Security-Policy. GET records a visit; HEAD does not.'
content:
text/html:
schema:
type: string
'302':
description: Redirect to targetUrl, or the matching rule's (query string not forwarded). GET records a visit; HEAD does not.
headers:
Location:
schema:
type: string
'404':
description: Unknown slug, or not served on this host
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'410':
description: Link is paused
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: getRBySlug
x-operation-id-source: derived
servers:
- url: https://esyurl.fyi
/robots.txt:
get:
tags:
- Public
summary: Disallows all crawling
security: []
responses:
'200':
description: robots.txt
content:
text/plain:
schema:
type: string
operationId: getRobotsTxt
x-operation-id-source: derived
servers:
- url: https://esyurl.fyi
/x402/qr:
post:
tags:
- Public
summary: 'A styled QR code for any text, paid per image with x402: no account or API key'
x-payment-info:
price:
mode: fixed
currency: USD
amount: '0.01'
protocols:
- x402: {}
description: The same body as POST /v1/render (free with an API key). Without a payment the answer is 402 with a PaymentRequired (body and base64 `PAYMENT-REQUIRED` header); repeat with `PAYMENT-SIGNATURE` (x402 v2, exact, USDC). The image comes back with a base64 `PAYMENT-RESPONSE`. Invalid input is 400 and never charged.
security: []
parameters:
- name: PAYMENT-SIGNATURE
in: header
required: false
schema:
type: string
description: Base64 x402 PaymentPayload (`X-PAYMENT` is accepted too)
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RenderRequest'
responses:
'200':
description: Image
content:
image/png:
schema:
type: string
format: binary
image/svg+xml:
schema:
type: string
headers:
PAYMENT-RESPONSE:
schema:
type: string
description: Base64 x402 SettlementResponse
'400':
description: Invalid input (nothing charged)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'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
'503':
description: '`payments_not_configured` or `service_unavailable` (nothing charged)'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: postX402Qr
x-operation-id-source: derived
get:
tags:
- Public
summary: The same as POST /x402/qr, with query parameters (no picture)
security: []
parameters:
- name: data
in: query
required: true
schema:
type: string
maxLength: 2048
- name: format
in: query
schema:
type: string
enum:
- png
- svg
default: png
- name: modules
in: query
schema:
type: string
enum:
- square
- rounded
- dot
- row
- column
description: Shape of the data modules (default square)
- name: eyeFrame
in: query
schema:
type: string
enum:
- square
- rounded
- circle
description: Outer ring of the three corner markers
- name: eyeBall
in: query
schema:
type: string
enum:
- square
- rounded
- circle
description: Centre of the corner markers
- name: size
in: query
schema:
type: integer
minimum: 64
maximum: 2048
default: 512
- name: margin
in: query
schema:
type: integer
minimum: 0
maximum: 16
default: 4
- name: dark
in: query
schema:
$ref: '#/components/schemas/HexColour'
description: 'URL-encode #, or omit it'
- name: light
in: query
schema:
$ref: '#/components/schemas/HexColour'
- name: ecl
in: query
schema:
type: string
enum:
- L
- M
- Q
- H
default: M
responses:
'200':
description: Image
content:
image/png:
schema:
type: string
format: binary
image/svg+xml:
schema:
type: string
'402':
description: Payment required
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequired'
operationId: getX402Qr
x-operation-id-source: derived
servers:
- url: https://esyurl.fyi
components:
schemas:
Slug:
type: string
pattern: ^[a-zA-Z0-9_-]{3,64}$
description: Globally unique and immutable. Route names (health, v1, mcp, r, api, admin, www, ...) are reserved.
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: {}
HexColour:
type: string
pattern: ^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
examples:
- '#000000'
RenderRequest:
type: object
required:
- data
additionalProperties: false
properties:
data:
type: string
maxLength: 2048
format:
type: string
enum:
- png
- svg
default: png
size:
type: integer
minimum: 64
maximum: 2048
margin:
type: integer
minimum: 0
maximum: 16
dark:
$ref: '#/components/schemas/HexColour'
light:
$ref: '#/components/schemas/HexColour'
ecl:
type: string
enum:
- L
- M
- Q
- H
modules:
type: string
enum:
- square
- rounded
- dot
- row
- column
description: Shape of the data modules (default square)
eyeFrame:
type: string
enum:
- square
- rounded
- circle
description: Outer ring of the three corner markers
eyeBall:
type: string
enum:
- square
- rounded
- circle
description: Centre of the corner markers
eyeColor:
$ref: '#/components/schemas/HexColour'
description: Colour of the corner markers; defaults to dark
image:
type: object
required:
- mode
- data
additionalProperties: false
properties:
mode:
type: string
enum:
- logo
- halftone
description: 'logo: in the middle; halftone: a photo behind the code, drawn as dots'
data:
type: string
description: data:image/png;base64,... (png, jpeg, webp or gif, up to 2 MB)
size:
type: number
minimum: 0.1
maximum: 0.3
description: Logo side as a share of the code (default 0.22)
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