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/codai-ro:codai-ro-lists-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: 3.2.0
info:
title: Codai Ro Lists API
version: '1'
description: 'Operations tagged Lists across 2 of this provider''s published API definitions: codai-ro-gateway-openapi.json, codai-ro-gateway-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://ai.codai.ro
description: Production
security:
- bearerAuth: []
tags:
- name: Lists
description: 'Lists and Share to codai: Inbox, Wishlist, Notes (presets, created on first use) and your own lists, filled
from the OS share sheet, the desktop, the hub, MCP or the API. Sharing is instant; link unfurling (title,
image, price, availability) and the Inbox list suggestion run in the background and are announced on
`GET /v1/lists/stream`. Images, video and PDFs (at most 10 MB) are uploaded first with tus (`/v1/uploads`,
metadata `purpose=list`) and attached by `media_key`. Every route needs an API key and only sees your lists.'
paths:
/v1/lists:
get:
operationId: listLists
tags:
- Lists
summary: List lists
description: All your lists in share-sheet order. The presets (Inbox, Wishlist, Notes) are created on the first call. Archived lists are included only with `archived=1`.
parameters:
- $ref: '#/components/parameters/RequestId'
- name: archived
in: query
required: false
description: '`1` to include archived lists.'
schema:
type: string
enum:
- '1'
responses:
'200':
description: OK.
content:
application/json:
schema:
type: object
required:
- lists
properties:
lists:
type: array
items:
$ref: '#/components/schemas/List'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createList
tags:
- Lists
summary: Create a list
description: Creates a custom list. It appears in the share sheet unless `show_in_share` is false.
parameters:
- $ref: '#/components/parameters/RequestId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListCreateInput'
responses:
'201':
description: Created.
content:
application/json:
schema:
type: object
required:
- list
properties:
list:
$ref: '#/components/schemas/List'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
servers:
- url: https://ai.codai.ro
description: Production
/v1/lists/order:
patch:
operationId: reorderLists
tags:
- Lists
summary: Reorder lists
description: Sets the order of your lists (also the order of the share-sheet targets). Unknown or foreign ids are ignored.
parameters:
- $ref: '#/components/parameters/RequestId'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- ids
properties:
ids:
type: array
minItems: 1
maxItems: 200
items:
type: string
format: uuid
responses:
'200':
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/ListOk'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
servers:
- url: https://ai.codai.ro
description: Production
/v1/lists/stream:
get:
operationId: streamLists
tags:
- Lists
summary: Stream list changes
description: 'Server-sent `list` events (`data: {"op", "listId"?, "itemId"?}`, `op` one of `lists`, `item`, `item_delete`) whenever a list or item changes on any device, including background enrichment. Keepalive comments every 25 s; closed after 30 min.'
parameters:
- $ref: '#/components/parameters/RequestId'
responses:
'200':
description: OK.
content:
text/event-stream:
schema:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
servers:
- url: https://ai.codai.ro
description: Production
/v1/lists/items/{itemId}:
patch:
operationId: updateListItem
tags:
- Lists
summary: Update a list item
description: Partial update of title, body, done, pinned or reminder; `list_id` moves the item to another of your lists.
parameters:
- $ref: '#/components/parameters/RequestId'
- name: itemId
in: path
required: true
description: Item id.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListItemPatchInput'
responses:
'200':
description: OK.
content:
application/json:
schema:
type: object
required:
- item
properties:
item:
$ref: '#/components/schemas/ListItem'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteListItem
tags:
- Lists
summary: Delete a list item
description: Deletes the item and its uploaded media, if any.
parameters:
- $ref: '#/components/parameters/RequestId'
- name: itemId
in: path
required: true
description: Item id.
schema:
type: string
format: uuid
responses:
'200':
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/ListOk'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
servers:
- url: https://ai.codai.ro
description: Production
/v1/lists/items/{itemId}/image:
get:
operationId: getListItemImage
tags:
- Lists
summary: Get an item image
description: The item's own uploaded image, or the preview image found while unfurling its link, fetched through an SSRF-guarded proxy. Cached privately for 24 h.
parameters:
- $ref: '#/components/parameters/RequestId'
- name: itemId
in: path
required: true
description: Item id.
schema:
type: string
format: uuid
responses:
'200':
description: The image bytes.
content:
image/*:
schema:
type: string
format: binary
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
servers:
- url: https://ai.codai.ro
description: Production
/v1/lists/{id}:
patch:
operationId: updateList
tags:
- Lists
summary: Update a list
description: Partial update of name, icon, color, share-sheet visibility, price watch or archived state. Works on presets too.
parameters:
- $ref: '#/components/parameters/RequestId'
- name: id
in: path
required: true
description: List id.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListPatchInput'
responses:
'200':
description: OK.
content:
application/json:
schema:
type: object
required:
- list
properties:
list:
$ref: '#/components/schemas/List'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteList
tags:
- Lists
summary: Delete a list
description: Deletes a custom list and its items. Presets cannot be deleted (409 `preset_list`); hide them from the share sheet or archive them instead.
parameters:
- $ref: '#/components/parameters/RequestId'
- name: id
in: path
required: true
description: List id.
schema:
type: string
format: uuid
responses:
'200':
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/ListOk'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: 'The list is a preset (`code: preset_list`).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://ai.codai.ro
description: Production
/v1/lists/{id}/items:
get:
operationId: listListItems
tags:
- Lists
summary: List items of a list
description: Items of one list, pinned first, then newest. Done items are included only with `done=1`.
parameters:
- $ref: '#/components/parameters/RequestId'
- name: id
in: path
required: true
description: List id.
schema:
type: string
format: uuid
- name: done
in: query
required: false
description: '`1` to include done items.'
schema:
type: string
enum:
- '1'
- name: limit
in: query
required: false
description: Maximum number of items.
schema:
type: integer
minimum: 1
default: 200
responses:
'200':
description: OK.
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/ListItem'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: addListItem
tags:
- Lists
summary: Add an item to a list
description: Adds text, a link or uploaded media (`media_key` = a finished tus upload created with `purpose=list`). Idempotent on `client_id` and on the canonical URL within the list; a duplicate returns 200 with the existing item and `created` false. Link unfurling runs in the background and is announced on the stream.
parameters:
- $ref: '#/components/parameters/RequestId'
- name: id
in: path
required: true
description: List id.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListItemInput'
responses:
'200':
description: Duplicate; the existing item.
content:
application/json:
schema:
$ref: '#/components/schemas/ListItemCreated'
'201':
description: Created.
content:
application/json:
schema:
$ref: '#/components/schemas/ListItemCreated'
'400':
description: 'Invalid body, or the uploaded media has an unsupported type (`code: bad_media`).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'413':
description: 'The uploaded media is larger than 10 MB (`code: bad_media`).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://ai.codai.ro
description: Production
/v1/lists/{id}/export.md:
get:
operationId: exportListMarkdown
tags:
- Lists
summary: Export a list as Markdown
description: The whole list (up to 500 items, done ones as checked boxes) as a GitHub-flavoured Markdown attachment.
parameters:
- $ref: '#/components/parameters/RequestId'
- name: id
in: path
required: true
description: List id.
schema:
type: string
format: uuid
responses:
'200':
description: The Markdown file.
content:
text/markdown:
schema:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
servers:
- url: https://ai.codai.ro
description: Production
/v1/share:
post:
operationId: shareToList
tags:
- Lists
summary: Share to codai
description: 'Share-sheet entry point. Target: `list_id`, a `preset`, or neither / `auto: true` (the item lands in Inbox and the model suggests a list in the background as `enrichment.suggestedListId`). The response is immediate; unfurl and suggestion arrive on the stream. Same idempotency as adding an item.'
parameters:
- $ref: '#/components/parameters/RequestId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ShareRequest'
responses:
'200':
description: Duplicate; the existing item.
content:
application/json:
schema:
$ref: '#/components/schemas/ShareResponse'
'201':
description: Created.
content:
application/json:
schema:
$ref: '#/components/schemas/ShareResponse'
'400':
description: 'Invalid body, or the uploaded media has an unsupported type (`code: bad_media`).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'413':
description: 'The uploaded media is larger than 10 MB (`code: bad_media`).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://ai.codai.ro
description: Production
components:
responses:
Unauthorized:
description: Missing, malformed, revoked or paused API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: No such resource, or it belongs to another account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Malformed body or query; `details` holds the flattened field errors.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
ListItemEnrichment:
type: object
description: Filled in the background by link unfurling, the Inbox suggestion and the price watch. Every field is optional.
properties:
siteName:
type: string
image:
type: string
format: uri
description: Preview image URL; read it through `GET /v1/lists/items/{itemId}/image`.
description:
type: string
price:
type: object
required:
- amount
- currency
properties:
amount:
type: number
example: 249.99
currency:
type: string
example: RON
availability:
type: string
enum:
- in_stock
- out_of_stock
- preorder
- unknown
suggestedListId:
type: string
format: uuid
description: Inbox auto-sort, the list the model suggested; you confirm it by moving the item.
fetchedAt:
type: string
format: date-time
watchedAt:
type: string
format: date-time
error:
type: string
ShareResponse:
type: object
required:
- item
- list
- created
properties:
item:
$ref: '#/components/schemas/ListItem'
list:
$ref: '#/components/schemas/List'
created:
type: boolean
ListCreateInput:
type: object
additionalProperties: false
required:
- name
properties:
name:
type: string
minLength: 1
maxLength: 80
example: Books
icon:
type:
- string
- 'null'
maxLength: 40
pattern: ^[a-z0-9-]+$
description: Lucide icon name.
example: book-open
color:
type:
- string
- 'null'
pattern: ^(#[0-9a-fA-F]{6}|[a-z]+(-\d{2,3})?)$
description: Hex color or a palette token such as `violet-500`.
show_in_share:
type: boolean
default: true
price_watch:
type: boolean
default: false
ShareRequest:
type: object
additionalProperties: false
description: Same fields as an item, plus the target. Without `list_id` and `preset` the share goes to Inbox in auto mode.
properties:
text:
type: string
maxLength: 20000
url:
type: string
format: uri
maxLength: 4000
example: https://example.com/product/42
title:
type: string
maxLength: 300
media_key:
type: string
minLength: 1
maxLength: 500
mime:
type: string
maxLength: 120
client_id:
type: string
minLength: 1
maxLength: 120
remind_at:
type:
- string
- 'null'
format: date-time
source:
$ref: '#/components/schemas/ListItemSource'
list_id:
type: string
format: uuid
preset:
type: string
enum:
- inbox
- wishlist
- notes
auto:
type: boolean
description: Inbox plus a background list suggestion; the default when no target is given.
ListItemSource:
type: object
additionalProperties: false
description: Where the item came from.
properties:
app:
type: string
maxLength: 120
example: com.android.chrome
device:
type: string
maxLength: 120
surface:
type: string
enum:
- phone
- desktop
- hub
- mcp
- cli
- wear
- api
ListItemCreated:
type: object
required:
- item
- created
properties:
item:
$ref: '#/components/schemas/ListItem'
created:
type: boolean
description: False when the item already existed (same `client_id` or canonical URL).
ListItemInput:
type: object
additionalProperties: false
description: At least one of `text`, `url` or `media_key` is required.
properties:
text:
type: string
maxLength: 20000
url:
type: string
format: uri
maxLength: 4000
example: https://example.com/product/42
title:
type: string
maxLength: 300
media_key:
type: string
minLength: 1
maxLength: 500
description: Id of a finished tus upload created with metadata `purpose=list`.
mime:
type: string
maxLength: 120
client_id:
type: string
minLength: 1
maxLength: 120
description: Client-generated idempotency key; resending it returns the existing item.
remind_at:
type:
- string
- 'null'
format: date-time
source:
$ref: '#/components/schemas/ListItemSource'
ListItemPatchInput:
type: object
additionalProperties: false
minProperties: 1
properties:
title:
type:
- string
- 'null'
maxLength: 300
body:
type:
- string
- 'null'
maxLength: 20000
done:
type: boolean
pinned:
type: boolean
remind_at:
type:
- string
- 'null'
format: date-time
list_id:
type: string
format: uuid
description: Moves the item to another of your lists.
ListOk:
type: object
required:
- ok
properties:
ok:
type: boolean
enum:
- true
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- message
- type
- code
properties:
message:
type: string
description: Human-readable, provider names redacted.
type:
type: string
enum:
- invalid_request_error
- subscription_required
- rate_limit_error
- upstream_error
- server_error
code:
type: string
enum:
- bad_request
- invalid_api_key
- subscription_inactive
- forbidden
- not_found
- payload_too_large
- rate_limit_exceeded
- quota_exceeded
- upstream_error
- internal_error
- not_a_member
- lease_held
- seq_conflict
- host_offline
- host_timeout
- rules_refused
- search_unavailable
- task_not_confirmable
- slug_taken
- project_has_environments
- already_has_env
- not_enrollable
- not_byo
- invalid_transition
- already_member
- vm_per_dev_single_member
- last_owner
- insufficient_balance
- key_scope_forbidden
- assets_unavailable
- asset_not_found
- too_many_renders
- renders_unavailable
- timeline_too_long
- not_a_timeline
- invalid_cursor
- templates_unavailable
- url_blocked
- invalid_tokens
- unsupported_media
- kind_mismatch
- node_not_found
- invalid_pick
- duplicate_key
- unknown_var
- invalid_var_value
- unsupported_kind
- too_long
- stale
- not_supported_for_kind
- unsupported_format
- too_large
- not_implemented
- version_conflict
- settings_unavailable
- ai_label_required
- sandbox_concurrency_limit
- sandbox_busy
- sandbox_daily_limit
- invalid_ttl
- workspace_too_large
- sandbox_paused_limit
- sandbox_capacity
details:
description: Present on `bad_request` (flattened Zod field errors), `invalid_tokens` (`issues`) and `rules_refused` (`tool`, `rule_id`, `decision`). Other codes never forward details over HTTP.
type: object
additionalProperties: true
examples:
- error:
message: Invalid or missing API key.
type: invalid_request_error
code: invalid_api_key
ListItem:
type: object
description: One item of a list.
required:
- id
- list_id
- client_id
- kind
- title
- body
- url
- media_key
- mime
- enrichment
- source
- pinned
- done
- remind_at
- created_at
- updated_at
properties:
id:
type: string
format: uuid
list_id:
type: string
format: uuid
client_id:
type:
- string
- 'null'
kind:
type: string
enum:
- text
- link
- product
- media
- file
title:
type:
- string
- 'null'
body:
type:
- string
- 'null'
url:
type:
- string
- 'null'
format: uri
media_key:
type:
- string
- 'null'
mime:
type:
- string
- 'null'
enrichment:
$ref: '#/components/schemas/ListItemEnrichment'
source:
$ref: '#/components/schemas/ListItemSource'
pinned:
type: boolean
done:
type: boolean
remind_at:
type:
- string
- 'null'
format: date-time
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
ListPatchInput:
type: object
additionalProperties: false
minProperties: 1
properties:
name:
type: string
minLength: 1
maxLength: 80
icon:
type:
- string
- 'null'
maxLength: 40
pattern: ^[a-z0-9-]+$
color:
type:
- string
- 'null'
pattern: ^(#[0-9a-fA-F]{6}|[a-z]+(-\d{2,3})?)$
show_in_share:
type: boolean
price_watch:
type: boolean
archived:
type: boolean
List:
type: object
description: A list. Presets (`inbox`, `wishlist`, `notes`) cannot be deleted; your own lists have `preset` = `custom`.
required:
- id
- name
- preset
- icon
- color
- position
- show_in_share
- price_watch
- archived
- created_at
- updated_at
properties:
id:
type: string
format: uuid
name:
type: string
example: Wishlist
preset:
type: string
enum:
- inbox
- wishlist
- notes
- custom
icon:
type:
- string
- 'null'
example: gift
color:
type:
- string
- 'null'
example: '#7c3aed'
position:
type: integer
show_in_share:
type: boolean
description: Shown as a target in the OS share sheet, the hub share page and the desktop hotkey.
price_watch:
type: boolean
description: Daily price and stock check of the list's product links.
archived:
type: boolean
item_count:
type: integer
description: Number of open items, when the endpoint computes it.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
parameters:
RequestId:
name: x-request-id
in: header
required: false
description: Client correlation id; echoed back as `x-codai-trace-id` and persisted on the usage row.
schema:
type: string
maxLength: 128
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: codai_…
description: A codai API key (`codai_` prefix). Ephemeral tokens from `POST /v1/tokens` are accepted only by the media surfaces matching their scope (`/v1/realtime`, `/v1/audio/*`, `/v1/embeddings`).
x-refined-from:
- codai-ro-gateway-openapi.json
- codai-ro-gateway-openapi.yml