sitey-my Domains API

openapi: 3.2.0
info:
  title: Sitey Domains API
  version: 1.0.0
  summary: 'Free subdomains with the DNS behind them: claim a name, point it at an address with an A or CNAME record, or send its visitors to a URL with a REDIRECT record, and add the TXT record a host asks for. Over REST or MCP, with or without an account.'
  description: 'Free subdomains with the DNS behind them: claim a name, point it at an address with an A or CNAME record, or send its visitors to a URL with a REDIRECT record, and add the TXT record a host asks for. Over REST or MCP, with or without an account.


    Limits:

    - An account may hold 5 subdomains and is refused the next one.

    - A caller with no API key is identified by an owner token. Creating without one mints it and returns it once, so nothing has to be fetched or signed up for first; send it back to manage the record from any address, and note that it cannot be looked up again. Records created before tokens existed are still identified by the IP address that made them. Either way the 5 is enforced, per token or per address.

    - Without an account (an API key from the dashboard) three things are refused: TXT records (ACCOUNT_REQUIRED); a CNAME or REDIRECT pointing at a temporary tunnel — trycloudflare.com, serveousercontent.com, serveo.net, ngrok.io, ngrok.app, ngrok-free.app, ngrok-free.dev, loca.lt, localtunnel.me, pinggy.link, pinggy.io, lhr.life, localhost.run, bore.pub, devtunnels.ms, tunnelmole.net — (TUNNEL_TARGET_FORBIDDEN); and names containing login, signin, verify, wallet, password, recovery, support, security, account, auth, bank (ACCOUNT_REQUIRED). An API key lifts all three. Brand names (toss, kakao, paypal and the like) are refused for everyone.

    - A name is lent, not given: 3 months for a record owned by an account, 1 month for one created without one. Every response carries expires_at, and renewal opens 14 days before it.

    - A record nobody renews is removed on that date.

    - Nothing can be bought while the payment route is off: a caller who is refused is refused, not offered a price.

    - A record created without an account is renewed free a month at a time. Paying for a year is switched off on this server.


    The same operations are available to an agent runtime over MCP at https://sitey.my/mcp (Streamable HTTP, one POST per message); https://sitey.my/.well-known/mcp.json describes it.'
servers:
- url: https://sitey.my
security:
- {}
- apiKey: []
- ownerToken: []
tags:
- name: Domains
paths:
  /api/v1/domains:
    get:
      summary: The roots you may create a subdomain under
      description: Call this first. Which roots are on offer is a row in a table, not a constant, and the first one in the list is the one the site itself uses.
      responses:
        '200':
          description: The active roots, canonical first.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      domains:
                        type: array
                        items:
                          type: string
                        example:
                        - sitey.my
                    required:
                    - domains
                required:
                - success
                - data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Domains
      operationId: getApiV1Domains
      x-operation-id-source: derived
components:
  responses:
    Unauthorized:
      description: UNAUTHORIZED — the Authorization header carried something that is neither an API key nor an owner token of ours. A malformed owner token is refused here rather than quietly demoted to an anonymous caller, which would answer `not found` for your own records.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: RATE_LIMITED — more than 100 requests in a minute from one address. Wait and repeat.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: 'INTERNAL_ERROR — ours, not yours. Nothing partial is left behind: a write that cannot finish is rolled back in full.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      description: Every failure has this shape. Branch on `code`, log `message`.
      properties:
        error:
          type: boolean
          const: true
        message:
          type: string
        code:
          type: string
      required:
      - error
      - message
      - code
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'An API key from the dashboard, sent as `Authorization: Bearer styo_…`. It makes the records belong to an account rather than to a token or an address.'
    ownerToken:
      type: http
      scheme: bearer
      description: 'An owner token, sent as `Authorization: Bearer anon_…`. You are not given one in advance and there is nothing to sign up for: create a subdomain with no Authorization header and the response carries one, once. Anything after `Bearer ` that is neither this nor an API key is refused rather than treated as anonymous.'
externalDocs:
  description: Docs
  url: https://sitey.my/docs