Admiral Public Start API

The public-start API from Admiral — 9 operation(s) for public-start.

GitHub OpenAPI

Operations 9

POST /public/start/read Start Read #
GET /public/start/read/{read_id} Get Read #
POST /public/start/unlock Unlock Read #
POST /public/start/seen Gate Seen #
GET /public/start/shot/{read_id}/{index} Get Shot #
GET /public/start/scan/{domain} Get Scan #
POST /public/start/draft Write Draft #
GET /public/start/draft/{draft_id} Get Draft #
POST /public/start/keep Keep Draft #

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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/meetadmiral-com:meetadmiral-com-public-start-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. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

meetadmiral-com-public-start-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Admiral Public Start API
  version: 0.1.0
tags:
- name: public-start
paths:
  /public/start/read:
    post:
      tags:
      - public-start
      summary: Start Read
      operationId: start_read_public_start_read_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /public/start/read/{read_id}:
    get:
      tags:
      - public-start
      summary: Get Read
      operationId: get_read_public_start_read__read_id__get
      parameters:
      - name: read_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Read Id
      - name: goal
        in: query
        required: false
        schema:
          type: string
          default: auto
          title: Goal
      - name: unlock
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Unlock
      - name: x-admiral-unlock
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Admiral-Unlock
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /public/start/unlock:
    post:
      tags:
      - public-start
      summary: Unlock Read
      description: 'Screen 4: the email that opens the rest of a finished read. It is a

        lead through the /talk form''s own door — the same rate limit, CRM row,

        attribution and notification — as source "scan", with the site it

        unlocked; then the read comes back whole with the token that keeps it

        open on this device.'
      operationId: unlock_read_public_start_unlock_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnlockBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /public/start/seen:
    post:
      tags:
      - public-start
      summary: Gate Seen
      description: 'The "See the rest" screen came into view for a finished read. Silent

        either way: a beacon that answered with errors would only tell a scraper

        which read ids exist. A repeat is dropped before the address''s daily

        quota is charged (Greptile on #368), so reloads cannot use it up.'
      operationId: gate_seen_public_start_seen_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SeenBody'
        required: true
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /public/start/shot/{read_id}/{index}:
    get:
      tags:
      - public-start
      summary: Get Shot
      description: 'One tile from the wall.


        A stable path rather than a signed URL, so the browser caches it instead

        of re-fetching every tile on every poll. It serves only what this read

        stored: the index is looked up in the row and the object key comes from

        there, never from the caller, so nothing else in the bucket can be

        reached by guessing a path.'
      operationId: get_shot_public_start_shot__read_id___index__get
      parameters:
      - name: read_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Read Id
      - name: index
        in: path
        required: true
        schema:
          type: integer
          title: Index
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /public/start/scan/{domain}:
    get:
      tags:
      - public-start
      summary: Get Scan
      description: 'The what-I-saw screen as a page: the latest read of a domain,

        whoever asked for it. Noindex on the web side.


        A read that is still running is returned too, and the page polls it.

        This used to answer 404 until the read was over, so the live checklist

        the page draws for a running read could never appear on it — somebody

        who opened the link mid-read was told the site had not been read, then

        had to reload to see anything (review on #213). A failed read is still

        a 404: there is nothing on it to show.'
      operationId: get_scan_public_start_scan__domain__get
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
          title: Domain
      - name: goal
        in: query
        required: false
        schema:
          type: string
          default: auto
          title: Goal
      - name: unlock
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Unlock
      - name: x-admiral-unlock
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Admiral-Unlock
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /public/start/draft:
    post:
      tags:
      - public-start
      summary: Write Draft
      operationId: write_draft_public_start_draft_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DraftBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /public/start/draft/{draft_id}:
    get:
      tags:
      - public-start
      summary: Get Draft
      operationId: get_draft_public_start_draft__draft_id__get
      parameters:
      - name: draft_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Draft Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /public/start/keep:
    post:
      tags:
      - public-start
      summary: Keep Draft
      description: 'The one thing asked for: an email to send the link to. The browser

        sends the sign-in link itself; this records which email the draft was

        kept for, so the claim on sign-in can check the two match.'
      operationId: keep_draft_public_start_keep_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeepBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    DraftBody:
      properties:
        read_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Read Id
        website:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Website
        description:
          anyOf:
          - type: string
            maxLength: 600
          - type: 'null'
          title: Description
        goal:
          type: string
          maxLength: 120
          title: Goal
        goal_key:
          type: string
          maxLength: 20
          title: Goal Key
          default: other
        budget_key:
          type: string
          maxLength: 20
          title: Budget Key
        area:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Area
        offers:
          items:
            type: string
          type: array
          maxItems: 12
          title: Offers
      type: object
      required:
      - goal
      - budget_key
      title: DraftBody
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SeenBody:
      properties:
        read_id:
          type: string
          format: uuid
          title: Read Id
        analytics_id:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Analytics Id
      type: object
      required:
      - read_id
      title: SeenBody
    UnlockBody:
      properties:
        read_id:
          type: string
          format: uuid
          title: Read Id
        email:
          type: string
          maxLength: 320
          title: Email
        click:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Click
        analytics_id:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Analytics Id
        company_url:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Company Url
      type: object
      required:
      - read_id
      - email
      title: UnlockBody
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ReadBody:
      properties:
        website:
          type: string
          maxLength: 500
          title: Website
      type: object
      required:
      - website
      title: ReadBody
    KeepBody:
      properties:
        draft_id:
          type: string
          format: uuid
          title: Draft Id
        email:
          type: string
          maxLength: 320
          title: Email
      type: object
      required:
      - draft_id
      - email
      title: KeepBody