Admiral Public Start API
The public-start API from Admiral — 9 operation(s) for public-start.
The public-start API from Admiral — 9 operation(s) for public-start.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/meetadmiral-com:meetadmiral-com-public-start-api"
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.
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: 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