# Suede AI Developer Docs: full text > The complete public text of docs.suedeai.ai, one section per page, for AI assistants and offline readers. The pages themselves are the source of truth; this file is generated from them by scripts/build-docs-seo.mjs. The shorter index is https://docs.suedeai.ai/llms.txt. Publisher: Suede AI (https://suedeai.ai), also known as Suede Labs. Founder: Jason Colapietro (https://suedeai.ai/founder). Prices and request fields on the API pages were checked against the live discovery documents on app.suedeai.ai; those documents (https://app.suedeai.ai/.well-known/x402 and https://app.suedeai.ai/api/v1/catalog) carry the current values. --- ## Suede AI Developer Docs | x402 APIs and Creator IP URL: https://docs.suedeai.ai/ Last updated: 2026-11-15 > Read Suede AI developer docs for programmable IP, creator ownership, provenance, licensing, and x402 agent-commerce APIs. Browse the canonical GitHub source. ### Suede AI developer docs for programmable IP Suede AI developer docs explain the public interfaces, rights concepts, and agent-commerce discovery surfaces in the Suede ecosystem. The canonical documentation is maintained in the [Suede-AI/suede-docs repository](https://github.com/Suede-AI/suede-docs) on GitHub. #### API guides: pay-per-call endpoints Suede sells music, video and image generation per call over x402, paid in USDC on Base with no account or API key. These guides cover the full integration, checked against the live API on 2026-10-11. For prices and request fields, the live discovery documents on `app.suedeai.ai` are the source of truth, and each guide links the documents it was checked against. 1. [Quickstart](https://docs.suedeai.ai/quickstart): send a request, read the 402 challenge, sign an EIP-3009 USDC authorization, retry with `PAYMENT-SIGNATURE`, and poll for the result. 2. [Endpoints](https://docs.suedeai.ai/endpoints): the three paid endpoints, their prices, shared payment terms, request headers and asynchronous mode. 3. [Create Music](https://docs.suedeai.ai/endpoints/create-music): `POST /create-music`, a full original song from a prompt, $0.50. 4. [Agent Video](https://docs.suedeai.ai/endpoints/agent-video): `POST /agent/video`, an 8-second 720p clip with native audio, $4.99. 5. [Agent Image](https://docs.suedeai.ai/endpoints/agent-image): `POST /agent/image`, one PNG or JPEG, $0.15. 6. [Errors and limits](https://docs.suedeai.ai/errors): status codes, error bodies, rate limits, idempotency and versioning. 7. [Python SDK](https://docs.suedeai.ai/python-sdk): `pip install suede-ai`, a client that signs and retries the payment for you. 8. [Discovery and MCP](https://docs.suedeai.ai/discovery): the x402 manifest, OpenAPI spec, catalog, A2A agent card and MCP server. #### What is Suede AI? Suede AI, also known as Suede Labs AI, is a company founded in 2024 by Jason Colapietro and based in West Palm Beach, Florida. Its official company website is [suedeai.ai](https://suedeai.ai), and its SEO and AEO practice is [Suede AI SEO](https://suedeai.agency/). These developer docs cover the company's creator products, programmable IP, provenance, rights metadata, licensing workflows, and agent-commerce interfaces, including x402 and ACP discovery surfaces. #### What are Suede's core pillars? - **Programmable IP:** interfaces for recording provenance, rights metadata, and machine-readable usage terms. - **Creator ownership:** documentation for connecting creative work to creator-supplied identity and rights context. - **Provenance:** source and metadata records that help people and software inspect where a media asset came from. - **Licensing:** documented workflows for publishing terms and reviewing license activity. - **Agent commerce:** public x402 and ACP discovery files that describe available services and current prices. #### Who maintains the public docs? Suede AI maintains this index and the canonical docs repository. For current leadership background, see [Jason Colapietro's public profile](https://suedeai.ai/founder). #### Where do the full developer docs live? The canonical, most current public documentation is maintained on GitHub at [Suede-AI/suede-docs](https://github.com/Suede-AI/suede-docs): full product directory, x402/ACP endpoint table, token references, and language guide. This page mirrors the core facts; the GitHub README is the source of truth. [Read the full docs on GitHub](https://github.com/Suede-AI/suede-docs) #### What does Suede expose for AI agents (x402/ACP)? Suede publishes public x402 and ACP discovery surfaces for agent-callable media and rights services. Use the [live agent-commerce catalog](https://app.suedeai.ai/api/v1/catalog) for current availability and prices, and the [x402 discovery document](https://app.suedeai.ai/.well-known/x402) for machine-readable routes. On 2026-10-11 the catalog held three endpoints, each paid per call in USDC on Base: [Create Music](https://docs.suedeai.ai/endpoints/create-music) at $0.50, [Agent Video](https://docs.suedeai.ai/endpoints/agent-video) at $4.99 and [Agent Image](https://docs.suedeai.ai/endpoints/agent-image) at $0.15. The same offerings are published as an OpenAPI spec, an A2A agent card and an MCP server; the [discovery guide](https://docs.suedeai.ai/discovery) lists every format. #### Where can I browse Suede sites and apps? The [Suede Universe Map](https://map.suedeai.ai) is a plain-English directory of public Suede sites, apps, and endpoints. For the practice behind Suede's AI visibility work, and the method published in full, see [Suede SEO](https://suedeai.agency/). #### Notes from the Suede AI team Longer write-ups from Jason Colapietro and the Suede AI team in West Palm Beach, Florida, on how these docs are built and what agencies can take from them. - [Writing developer docs that AI assistants quote correctly](https://docs.suedeai.ai/notes/ai-quotable-developer-docs): the source, date and verification rules behind this site. - [Model Context Protocol for agencies](https://docs.suedeai.ai/notes/mcp-for-agencies-south-florida): a South Florida primer built around the Suede MCP server. - [From open source to docs](https://docs.suedeai.ai/notes/open-source-to-docs): lessons from 54 merged pull requests across 46 repositories. - [An API documentation checklist for agency-built integrations](https://docs.suedeai.ai/notes/api-docs-checklist-agency-integrations): what a South Florida agency should document before handing off a client integration. - [Writing llms.txt that answer engines actually use](https://docs.suedeai.ai/notes/llms-txt-worked-example): a worked example built from this site's own file. All notes live in the [notes index](https://docs.suedeai.ai/notes). #### Related Suede tools for x402 sellers - [AI Agent Builder & Workflow Automation](https://agents.suedeai.ai): build AI agents visually for leads, invoices and reports. Test workflows, inspect every run, and publish paid x402 APIs when payments are enabled. - [Suede ACP/x402 Performance Engine](https://perform.suedeai.ai): score your ACP/x402 readiness in 60 seconds. Free, no account required. - [Agentix: x402 AI Agent Earnings Tracker for USDC on Base](https://agentix.suedeai.ai): the portfolio tracker for the x402 agents you've launched, with total USDC earned on Base, calls, per-agent performance, status, and trend. Not what you were looking for? [Go straight to the GitHub repo](https://github.com/Suede-AI/suede-docs). Part of the [Suede Universe Map](https://map.suedeai.ai). --- ## x402 Quickstart: Pay a Suede API Call | Suede AI Docs URL: https://docs.suedeai.ai/quickstart Last updated: 2026-10-11 > Pay a Suede AI endpoint over x402: read the 402 challenge, sign an EIP-3009 USDC authorization on Base, retry with PAYMENT-SIGNATURE, then poll the job. ### Pay a Suede x402 endpoint in five steps Suede AI sells music, video and image generation per call over x402. There is no account and no API key: your wallet signs a USDC payment on Base, and the same HTTP request carries it. This guide follows the flow the live endpoints at `app.suedeai.ai` run, checked on 2026-10-11. #### What you need - **USDC on Base mainnet** in a wallet you control. The lowest-priced call, [Agent Image](https://docs.suedeai.ai/endpoints/agent-image), costs $0.15. - **A way to sign EIP-712 typed data**, such as viem, ethers or eth-account. The [suede-ai Python SDK](https://docs.suedeai.ai/python-sdk) does the signing for you. - **No ETH for gas.** Under the x402 `exact` scheme the facilitator submits the transfer and pays the gas. Your signature fixes the amount and the recipient, and the facilitator cannot change either. #### 1. Read the price from the discovery document Prices are enforced on the server, so read them before you sign. The x402 discovery document lists every paid resource: ``` curl -s https://app.suedeai.ai/.well-known/x402 \ | jq -r '.resources[] | "\(.method) \(.resource) \(.priceUsd)"' ``` On 2026-10-11 it returned three resources: ``` POST https://app.suedeai.ai/create-music $0.50 POST https://app.suedeai.ai/agent/video $4.99 POST https://app.suedeai.ai/agent/image $0.15 ``` The [discovery page](https://docs.suedeai.ai/discovery) covers the other machine-readable formats, including OpenAPI, the product catalog and the MCP server. #### 2. Send the request and read the 402 challenge Send the request you want to buy, with no payment attached: ``` curl -i -X POST https://app.suedeai.ai/agent/image \ -H 'Content-Type: application/json' \ -d '{"prompt":"Album cover, neon city at night, rain on glass","aspectRatio":"1:1","outputFormat":"png"}' ``` The server answers `402 Payment Required`. The challenge comes twice: as base64-encoded JSON in the `PAYMENT-REQUIRED` header, and as the same JSON in the body. Trimmed to the fields you sign against: ``` HTTP/2 402 content-type: application/json payment-required: eyJ4NDAyVmVyc2lvbiI6IDIs... suede-api-version: 1 { "x402Version": 2, "error": "PAYMENT-SIGNATURE header is required", "resource": { "url": "https://app.suedeai.ai/agent/image" }, "accepts": [{ "scheme": "exact", "network": "eip155:8453", "maxAmountRequired": "150000", "amount": "150000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x10FF767043A1723E0BB5B9207bC37D3442cC9E4F", "maxTimeoutSeconds": 300, "extra": { "name": "USD Coin", "version": "2", "decimals": 6, "priceUsd": "$0.15" } }] } ``` | Field | What it tells you | | --- | --- | | `network` | `eip155:8453` is Base mainnet. | | `asset` | The USDC contract on Base. It is also the EIP-712 `verifyingContract`. | | `amount` | The price in USDC base units. USDC has 6 decimals, so `150000` is $0.15. | | `payTo` | The address that receives the payment. | | `maxTimeoutSeconds` | 300 seconds on all three endpoints. | | `extra.name`, `extra.version` | The EIP-712 domain name and version: `"USD Coin"` and `"2"`. | To read the header copy instead of the body, decode it: ``` curl -s -o /dev/null -D - -X POST https://app.suedeai.ai/agent/image \ -H 'Content-Type: application/json' -d '{"prompt":"test"}' \ | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' \ | base64 -d | jq '.accepts[0]' ``` An unpaid request gets the 402 even when the body is empty, so the challenge does not mean your body is valid. Check it against the [endpoint reference](https://docs.suedeai.ai/endpoints) before you sign. #### 3. Sign an EIP-3009 authorization USDC supports EIP-3009 `transferWithAuthorization`, so paying is a signature over EIP-712 typed data. You do not send a transaction yourself. Fill the typed data from the `accepts` entry: ``` domain name "USD Coin" accepts[0].extra.name version "2" accepts[0].extra.version chainId 8453 verifyingContract 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 accepts[0].asset primaryType TransferWithAuthorization from address your wallet to address 0x10FF767043A1723E0BB5B9207bC37D3442cC9E4F accepts[0].payTo value uint256 150000 accepts[0].amount validAfter uint256 a Unix time slightly in the past validBefore uint256 a Unix time later than now + maxTimeoutSeconds nonce bytes32 32 random bytes ``` For reference, the suede-ai SDK sets `validAfter` to 60 seconds before now and `validBefore` to now plus the larger of 600 seconds and `maxTimeoutSeconds` plus 60. #### 4. Retry with the PAYMENT-SIGNATURE header Wrap the signature in an x402 version 2 `PaymentPayload`. The `accepted` field repeats the `accepts` entry you chose: ``` { "x402Version": 2, "resource": { "url": "https://app.suedeai.ai/agent/image" }, "accepted": { "scheme": "exact", "network": "eip155:8453", "amount": "150000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x10FF767043A1723E0BB5B9207bC37D3442cC9E4F", "maxTimeoutSeconds": 300, "extra": { "name": "USD Coin", "version": "2", "decimals": 6, "priceUsd": "$0.15" } }, "payload": { "signature": "0x...", "authorization": { "from": "0xYourWallet", "to": "0x10FF767043A1723E0BB5B9207bC37D3442cC9E4F", "value": "150000", "validAfter": "1791746000", "validBefore": "1791746660", "nonce": "0x..." } } } ``` Base64-encode that JSON and send the identical request again with it in `PAYMENT-SIGNATURE`. Add an `X-Idempotency-Key`: if you resend the same key and body within the cache window, you get the original response back without a second charge. ``` curl -i -X POST https://app.suedeai.ai/agent/image \ -H 'Content-Type: application/json' \ -H "PAYMENT-SIGNATURE: $PAYMENT" \ -H 'X-Idempotency-Key: cover-art-0001' \ -d '{"prompt":"Album cover, neon city at night, rain on glass","aspectRatio":"1:1","outputFormat":"png"}' ``` A paid call answers `202 Accepted` with a job to poll. The discovery document gives this example body: ``` { "jobId": "image-job-example", "status": "queued", "provider": "suede", "pollUrl": "https://app.suedeai.ai/agent/image/image-job-example" } ``` Paid calls are asynchronous by default because a render takes minutes and payment clients time out in about 30 seconds. To block until the asset is ready, add `?async=false` to the URL. Only the literal value `true` selects asynchronous mode: any other value, including `1`, `yes` and `on`, counts as `false` and blocks. The same header also accepts a Skyfire `pay+jwt` or `kya-pay+jwt` token in place of an x402 payload. #### 5. Poll for the result Polling is free: the job was paid for when it was created. Request `pollUrl` until the job reaches a final state. ``` curl -s https://app.suedeai.ai/agent/image/ ``` | Endpoint | Poll route | Finished when | Asset field | | --- | --- | --- | --- | | [/agent/image](https://docs.suedeai.ai/endpoints/agent-image) | `GET /agent/image/{jobId}` | `status` is `completed` or `failed` | `imageUrl` | | [/agent/video](https://docs.suedeai.ai/endpoints/agent-video) | `GET /agent/video/{jobId}` | `status` is `completed` or `failed` | `videoUrl` | | [/create-music](https://docs.suedeai.ai/endpoints/create-music) | `GET /api/songs/{songId}` | `model_version` is no longer `pending` | `audio_url` | For music, `audio_url` holds a placeholder cover image until the track is rendered, so check `model_version`, not `audio_url`. A value of `failed` is final. The [errors page](https://docs.suedeai.ai/errors) covers rate limits, retries and what is never charged. #### Skip the signing code The [suede-ai Python SDK](https://docs.suedeai.ai/python-sdk) runs steps 2 to 4 for you and returns the 202 body: ``` pip install suede-ai ``` ``` from suede_ai import SuedeClient with SuedeClient(wallet_private_key=PRIVATE_KEY) as suede: job = suede.agent_image(prompt="Album cover, neon city at night, rain on glass") print(job["pollUrl"]) ``` #### Sell your own x402 endpoint The same rail works in the other direction. [x402 Agent Builder: Get Paid Per Call](https://agents.suedeai.ai/x402-agent-builder): build an AI agent on a visual canvas, set a price per call, and get paid in USDC on Base through x402 once you enable payments. Dry runs need no wallet. #### Sources Every value on this page comes from these documents, fetched on 2026-10-11, and from live requests to the endpoints on the same day. - [app.suedeai.ai/.well-known/x402](https://app.suedeai.ai/.well-known/x402): prices, payment requirements and example responses. - [app.suedeai.ai/openapi.json](https://app.suedeai.ai/openapi.json): asynchronous execution, the `async` parameter, idempotency and poll routes. - [x402 HTTP transport, version 2](https://raw.githubusercontent.com/coinbase/x402/main/specs/transports-v2/http.md): the `PAYMENT-REQUIRED` and `PAYMENT-SIGNATURE` headers and the `PaymentPayload` shape. - [x402 exact scheme on EVM](https://raw.githubusercontent.com/coinbase/x402/main/specs/schemes/exact/scheme_exact_evm.md): EIP-3009 signing and who pays gas. - [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009): the `TransferWithAuthorization` type. - [suede-ai 0.4.0 on PyPI](https://pypi.org/project/suede-ai/): the SDK's signing window. --- ## Suede x402 API Endpoints and Prices | Suede AI Docs URL: https://docs.suedeai.ai/endpoints Last updated: 2026-10-11 > Three pay-per-call Suede AI endpoints for music, video and image generation, with prices, USDC amounts on Base, shared headers and poll routes. ### Suede x402 API endpoints Three endpoints, one payment rail. Each is a `POST` to `https://app.suedeai.ai`, priced per call in USDC on Base, and a paid call returns a job you can poll for free. The figures below come from the live discovery document and OpenAPI spec, checked on 2026-10-11. #### The three paid endpoints | Endpoint | What you get | Price | amount | Poll route | | --- | --- | --- | --- | --- | | [`POST /create-music`](https://docs.suedeai.ai/endpoints/create-music) | A complete original song with vocals, melody and full arrangement, as a finished MP3 | $0.50 | `500000` | `GET /api/songs/{songId}` | | [`POST /agent/video`](https://docs.suedeai.ai/endpoints/agent-video) | An 8-second 720p clip with native audio | $4.99 | `4990000` | `GET /agent/video/{jobId}` | | [`POST /agent/image`](https://docs.suedeai.ai/endpoints/agent-image) | One hosted still image, PNG or JPEG | $0.15 | `150000` | `GET /agent/image/{jobId}` | `amount` is the price in USDC base units (6 decimals), exactly as it appears in the 402 challenge and the value you sign. Each endpoint takes a JSON body in which `prompt` is the only required field. #### Payment terms shared by all three | Field | Value | | --- | --- | | `x402Version` | `2` | | `scheme` | `exact` | | `network` | `eip155:8453` (Base mainnet) | | `asset` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` (USDC; EIP-712 domain `"USD Coin"`, version `"2"`) | | `payTo` | `0x10FF767043A1723E0BB5B9207bC37D3442cC9E4F` | | `maxTimeoutSeconds` | `300` | The same `PAYMENT-SIGNATURE` header also accepts Skyfire `pay+jwt` and `kya-pay+jwt` tokens. The product catalog lists Stripe Checkout as a second payment method at the same USD prices: 50, 499 and 15 cents. The [quickstart](https://docs.suedeai.ai/quickstart) walks through the x402 payment step by step. #### Request headers | Header | Required | Use | | --- | --- | --- | | `Content-Type: application/json` | Yes | All three endpoints take a JSON body. | | `PAYMENT-SIGNATURE` | For a paid call | A base64 x402 `PaymentPayload` or a Skyfire token. Leave it off the first call to receive the 402 challenge. | | `X-Idempotency-Key` | No | Up to 200 characters. Resending the same key and body within the cache window returns the original response without charging again. | | `Suede-API-Version` | No | Pins the API version. The current and only supported value is `1`. | #### Asynchronous by default A call that carries `PAYMENT-SIGNATURE` queues the job and answers `202 Accepted` with a `pollUrl`. Renders take minutes, and x402 and Skyfire clients time out in about 30 seconds, so this keeps your payment client from timing out mid-render. Polling needs no further payment. - `?async=false` forces a blocking call that answers `200` with the finished asset. - `?async=true` queues the job. Only the literal `true` selects asynchronous mode; `1`, `yes` and `on` count as `false`. - The body field `asyncMode` can switch asynchronous mode on, never off. `"asyncMode": false` leaves a paid call asynchronous. All three endpoints answer `202` for a queued job, so a `2xx` other than `202` means the asset is already in the body. #### Response codes | Status | Meaning | | --- | --- | | `202` | Paid call accepted and queued. Poll `pollUrl`. | | `200` | Blocking call finished, with the asset in the body. | | `400` | Bad request, for example an unsupported `Suede-API-Version`. | | `402` | Payment required, or the payment was not accepted. | | `422` | The body failed validation. A paid request that fails validation is not charged. | | `429` | Rate-limited. Wait for `Retry-After`. | | `5XX` | Server or upstream failure. Not charged; retry with the same `X-Idempotency-Key`. | Bodies, headers and retry rules for each code are on the [errors page](https://docs.suedeai.ai/errors). #### Sources - [app.suedeai.ai/.well-known/x402](https://app.suedeai.ai/.well-known/x402): resources, prices and payment requirements. - [app.suedeai.ai/openapi.json](https://app.suedeai.ai/openapi.json): headers, the `async` parameter and response codes. - [app.suedeai.ai/api/v1/catalog](https://app.suedeai.ai/api/v1/catalog): product descriptions and payment methods. For every machine-readable format these endpoints are published in, see [discovery documents and MCP server](https://docs.suedeai.ai/discovery). --- ## Create Music API: POST /create-music | Suede AI Docs URL: https://docs.suedeai.ai/endpoints/create-music Last updated: 2026-10-11 > POST /create-music turns a text prompt into a full original song for $0.50 USDC on Base. Request fields, the 202 job response and how to poll it. ### Create Music: POST /create-music Turn a text prompt into a complete original song, with vocals, melody and full arrangement, delivered as a finished MP3 rather than a loop or preview. One call costs $0.50 in USDC on Base. #### What it is for Describe the genre, mood, instrumentation and tempo, supply your own lyrics, ask for an instrumental, or pin a style tag. The discovery document names soundtracks under video, release-ready artist tracks, podcast and game themes, and demo sketches as uses. #### At a glance | | | | --- | --- | | Endpoint | `POST https://app.suedeai.ai/create-music` | | Price | $0.50, `amount` `500000` USDC base units | | Payment | x402 `exact` on `eip155:8453` to `0x10FF767043A1723E0BB5B9207bC37D3442cC9E4F`, or a Skyfire token | | Paid response | `202 Accepted` with `songId` and `pollUrl` | | Poll | `GET https://app.suedeai.ai/api/songs/{songId}`, free | | Identifiers | OpenAPI `operationId`, A2A skill and MCP tool: `create_music` | #### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `prompt` | string | Yes | The song you want: genre, mood, instruments and any specific vibe. Examples from the schema: "Upbeat 80s synthwave with driving bass and neon atmosphere", "A melancholic acoustic guitar ballad about rain". | | `style` | string | No | A style or genre tag, such as `Hip Hop`, `Ambient` or `Rock`. | | `custom_mode` | boolean | No | `true` to sing the lyrics you supply in `lyrics`. | | `lyrics` | string | When `custom_mode` is `true` | Your lyrics. | | `make_instrumental` | boolean | No | `true` for a track without vocals. | | `vocal_gender` | string | No | `m` or `f`. | | `tags` | string | No | Comma-separated keywords to tag the generated file. | | `asyncMode` | boolean | No | Switches asynchronous mode on, never off. Paid calls are already asynchronous. | #### Example: your own lyrics First send the request without `PAYMENT-SIGNATURE` to get the 402 challenge (`amount` `500000`, `priceUsd` `$0.50`), sign it as shown in the [quickstart](https://docs.suedeai.ai/quickstart), then send: ``` curl -i -X POST https://app.suedeai.ai/create-music \ -H 'Content-Type: application/json' \ -H "PAYMENT-SIGNATURE: $PAYMENT" \ -H 'X-Idempotency-Key: rain-ballad-0001' \ -d '{ "prompt": "A melancholic acoustic guitar ballad about rain", "style": "Ambient", "custom_mode": true, "lyrics": "Your lyrics here", "vocal_gender": "f" }' ``` For a track without vocals, drop `custom_mode` and `lyrics` and send `"make_instrumental": true`. #### Response to a paid call: 202 Accepted | Field | Description | | --- | --- | | `status` | `processing` or `queued`. | | `shareUrl` | The browser share URL the track will have once the job completes. | | `songId` | The id of the song row, and the `{songId}` in `pollUrl`. It can be `null` when the job is queued before that row exists. | | `pollUrl` | The absolute URL of `GET /api/songs/{songId}`. No further payment. | With `?async=false` the call blocks and answers `200` with `shareUrl` (a public page to listen to and download the track), `title` and `imageUrl` (cover art). Renders take minutes and payment clients time out in about 30 seconds, so the default asynchronous mode suits most callers. #### Polling: GET /api/songs/{songId} Music returns the song row, not the `jobId` and `status` shape the video and image polls use. Read `model_version`: - `pending`: the track is queued or rendering. Poll again. - `failed`: generation failed. This is final; stop polling. - Any version label, such as `v4.5`: the track is ready and `audio_url` is the finished MP3. Until the track is ready, `audio_url` holds the placeholder cover-image URL the row was created with. It is a reachable image, not audio, so a present `audio_url` does not mean the track is finished. | Field | Description | | --- | --- | | `id` | The `songId` you polled. | | `model_version` | The job state, as above. | | `audio_url` | The finished MP3 once ready; a placeholder image URL before that. | | `title`, `prompt`, `genre` | Track title, the prompt it was generated from, and the style label from the request. | | `image_url` | Cover art URL. | | `duration` | Length in seconds; `0` until the render finishes. | | `share_id` | Public share identifier for the listener page. | | `is_public` | `true` for x402 and Skyfire paid jobs, which are created public so the buyer can fetch them. | | `created_at` | Creation time, ISO 8601. | An unknown `songId` answers `404` with `{"error":"Song not found"}`. Because paid jobs are created public, a 404 means the id is wrong, not that the track is still rendering. #### Sources - [app.suedeai.ai/.well-known/x402](https://app.suedeai.ai/.well-known/x402): description, price, payment requirement and input schema (resource entry last updated 2026-08-30). - [app.suedeai.ai/openapi.json](https://app.suedeai.ai/openapi.json): operations `create_music` and `create_music_result`. - Live requests on 2026-10-11: the unpaid 402 challenge and the 404 for an unknown `songId`. --- ## Agent Video API: POST /agent/video | Suede AI Docs URL: https://docs.suedeai.ai/endpoints/agent-video Last updated: 2026-10-11 > POST /agent/video renders an 8-second 720p clip with native audio for $4.99 USDC on Base. Request fields, aspect ratios, the 202 job and polling. ### Agent Video: POST /agent/video Generate an 8-second 720p video clip with native audio from a text prompt. One call costs $4.99 in USDC on Base. #### What it is for Short-form video, b-roll, product shots, music-video visuals, social clips and ads. The audio is generated from the scene, so write the sound into the prompt: instruments, voices, weather, movement. A silent scene renders near-silent by design. #### At a glance | | | | --- | --- | | Endpoint | `POST https://app.suedeai.ai/agent/video` | | Price | $4.99, `amount` `4990000` USDC base units | | Payment | x402 `exact` on `eip155:8453` to `0x10FF767043A1723E0BB5B9207bC37D3442cC9E4F`, or a Skyfire token | | Output | An 8-second 720p clip with native audio | | Paid response | `202 Accepted` with `jobId` and `pollUrl` | | Poll | `GET https://app.suedeai.ai/agent/video/{jobId}`, free | | Identifiers | OpenAPI `operationId`, A2A skill and MCP tool: `agent_video` | #### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `prompt` | string | Yes | Narrative or visual prompt that drives the video concept. | | `durationSeconds` | integer | No | Requested length in seconds. Default `8`, minimum `3`, maximum `15`. The service maps it to a supported render length. | | `aspectRatio` | string | No | `16:9`, `9:16` or `1:1`. | | `asyncMode` | boolean | No | Switches asynchronous mode on, never off. Paid calls are already asynchronous. | #### Example: a vertical social clip Get the 402 challenge first (`amount` `4990000`, `priceUsd` `$4.99`), sign it as shown in the [quickstart](https://docs.suedeai.ai/quickstart), then send: ``` curl -i -X POST https://app.suedeai.ai/agent/video \ -H 'Content-Type: application/json' \ -H "PAYMENT-SIGNATURE: $PAYMENT" \ -H 'X-Idempotency-Key: vinyl-clip-0001' \ -d '{ "prompt": "Slow push-in on a spinning vinyl record, rain against the window, soft piano and the crackle of the needle", "aspectRatio": "9:16" }' ``` The prompt names its sounds (rain, piano, needle crackle) because the audio track is generated from what the scene describes. #### Response to a paid call: 202 Accepted The discovery document gives this example body: ``` { "jobId": "video-job-example", "status": "queued", "provider": "suede", "pollUrl": "https://app.suedeai.ai/agent/video/video-job-example" } ``` With `?async=false` the call blocks and answers `200` with the same body shape as the poll below, so one parser covers both paths. Renders take minutes and payment clients time out in about 30 seconds, so most callers should keep the default and poll. #### Polling: GET /agent/video/{jobId} Poll until `status` is `completed`, with `videoUrl` set, or `failed`. Both are final; `queued` and `processing` mean poll again. | Field | Description | | --- | --- | | `jobId` | The render's job identifier. | | `status` | `queued`, `processing`, `completed` or `failed`. | | `provider` | The provider handling the render. | | `videoUrl` | The generated video once complete; `null` until then. | | `videoId` | The Suede video record identifier, when available. | | `pageUrl` | The Suede share page, when available. | | `pollUrl` | Set on the 202 accept; `null` on a poll response. | An unknown or expired `jobId` answers `200` with `status` `failed`, not 404. On 2026-10-11 that response also carried `"error": "Generation failed. Please try again."` and an `etaSeconds` field set to `null`. #### Sources - [app.suedeai.ai/.well-known/x402](https://app.suedeai.ai/.well-known/x402): description, price, payment requirement, input schema and example output (resource entry last updated 2026-08-30). - [app.suedeai.ai/openapi.json](https://app.suedeai.ai/openapi.json): operations `agent_video` and `agent_video_status`. - Live requests on 2026-10-11: the unpaid 402 challenge and a poll for an unknown `jobId`. --- ## Agent Image API: POST /agent/image | Suede AI Docs URL: https://docs.suedeai.ai/endpoints/agent-image Last updated: 2026-10-11 > POST /agent/image returns one PNG or JPEG for $0.15 USDC on Base. Request fields, the ten aspect ratios, the 202 job response and the poll route. ### Agent Image: POST /agent/image Generate one hosted still image from a text prompt, as PNG or JPEG. One call costs $0.15 in USDC on Base, the lowest price of the three endpoints, which also makes it the cheapest way to test a full payment round trip. #### What it is for Album and single cover art, podcast and video thumbnails, social and campaign graphics, concept art, storyboard frames, product shots and article illustrations. Frame it square, portrait or widescreen. #### At a glance | | | | --- | --- | | Endpoint | `POST https://app.suedeai.ai/agent/image` | | Price | $0.15, `amount` `150000` USDC base units | | Payment | x402 `exact` on `eip155:8453` to `0x10FF767043A1723E0BB5B9207bC37D3442cC9E4F`, or a Skyfire token | | Output | One hosted PNG or JPEG | | Paid response | `202 Accepted` with `jobId` and `pollUrl` | | Poll | `GET https://app.suedeai.ai/agent/image/{jobId}`, free | | Identifiers | OpenAPI `operationId`, A2A skill and MCP tool: `agent_image` | #### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `prompt` | string | Yes | Visual prompt describing the image to generate. | | `aspectRatio` | string | No | One of `1:1`, `9:16`, `16:9`, `3:4`, `4:3`, `3:2`, `2:3`, `5:4`, `4:5`, `21:9`. | | `outputFormat` | string | No | `png` or `jpeg`. | | `asyncMode` | boolean | No | Switches asynchronous mode on, never off. Paid calls are already asynchronous. | The ten aspect ratios cover square (`1:1`), portrait (`4:5`, `3:4`, `2:3`, `9:16`) and landscape or widescreen (`5:4`, `4:3`, `3:2`, `16:9`, `21:9`) framing. #### Example: square cover art Get the 402 challenge first (`amount` `150000`, `priceUsd` `$0.15`), sign it as shown in the [quickstart](https://docs.suedeai.ai/quickstart), then send: ``` curl -i -X POST https://app.suedeai.ai/agent/image \ -H 'Content-Type: application/json' \ -H "PAYMENT-SIGNATURE: $PAYMENT" \ -H 'X-Idempotency-Key: cover-art-0001' \ -d '{ "prompt": "Album cover, neon city at night, rain on glass", "aspectRatio": "1:1", "outputFormat": "png" }' ``` #### Response to a paid call: 202 Accepted The discovery document gives this example body: ``` { "jobId": "image-job-example", "status": "queued", "provider": "suede", "pollUrl": "https://app.suedeai.ai/agent/image/image-job-example" } ``` With `?async=false` the call blocks and answers `200` with the same body shape as the poll below. #### Polling: GET /agent/image/{jobId} Poll until `status` is `completed`, with `imageUrl` set, or `failed`. Both are final; `queued` and `processing` mean poll again. | Field | Description | | --- | --- | | `jobId` | The render's job identifier. | | `status` | `queued`, `processing`, `completed` or `failed`. | | `provider` | The provider handling the render. | | `imageUrl` | The generated image once complete; `null` until then. | | `pollUrl` | Set on the 202 accept; `null` on a poll response. | An unknown or expired `jobId` answers `200` with `status` `failed`, not 404. On 2026-10-11 that response looked like this: ``` {"jobId":"unknown-job-id","imageUrl":null,"status":"failed","provider":"suede","pollUrl":null,"error":"Generation failed. Please try again."} ``` #### A polling loop in Python ``` import time import httpx def wait_for_image(poll_url: str) -> str | None: while True: job = httpx.get(poll_url).json() if job["status"] == "completed": return job["imageUrl"] if job["status"] == "failed": return None time.sleep(5) ``` The [suede-ai SDK](https://docs.suedeai.ai/python-sdk) handles the payment and returns the `pollUrl` this loop needs. #### Sources - [app.suedeai.ai/.well-known/x402](https://app.suedeai.ai/.well-known/x402): description, price, payment requirement, input schema and example output (resource entry last updated 2026-08-30). - [app.suedeai.ai/openapi.json](https://app.suedeai.ai/openapi.json): operations `agent_image` and `agent_image_status`. - Live requests on 2026-10-11: the unpaid 402 challenge and a poll for an unknown `jobId`. --- ## API Errors, Rate Limits and Retries | Suede AI Docs URL: https://docs.suedeai.ai/errors Last updated: 2026-10-11 > Status codes, error bodies, rate-limit headers, idempotency keys and API versioning for Suede AI x402 endpoints, and which requests are never charged. ### Errors, rate limits and retries Suede's x402 endpoints use standard HTTP status codes and a small JSON error body. This page lists what each code means, which requests are never charged, and how to retry safely. Example responses were captured from the live API on 2026-10-11. #### Status codes | Status | When | What to do | | --- | --- | --- | | `202` | A paid call was accepted and the job is queued. | Poll `pollUrl`. | | `200` | A blocking call (`?async=false`) finished, or a poll returned the job state. | Read the asset URL, or check `status` / `model_version`. | | `400` | Bad request, for example an unsupported `Suede-API-Version`. | Send `Suede-API-Version: 1` or leave the header out. | | `402` | No payment was attached, or the payment was not accepted. | Read `accepts`, sign, and retry with `PAYMENT-SIGNATURE`. | | `404` | A music poll for a `songId` that does not exist. | Use the `songId` from the 202 response. | | `422` | The request body failed validation. | Fix the fields listed in `detail` and retry. | | `429` | Rate-limited (`code`: `rate_limited`). | Wait the number of seconds in `Retry-After`. | | `5XX` | A server or upstream failure. | Retry with backoff, reusing the same `X-Idempotency-Key`. | #### Requests that are never charged - A paid request that fails validation (`422`). - A request that fails with a `5XX`. - Every poll: `GET /api/songs/{songId}`, `GET /agent/video/{jobId}` and `GET /agent/image/{jobId}`. - A resend with the same `X-Idempotency-Key` and body within the cache window, which returns the original response. #### Error bodies The 400, 422, 429 and `5XX` responses share the `Error` shape from the OpenAPI spec: `detail`, a message string, and `code`, a machine-readable value present where a client should branch on it. ``` {"detail":"Unsupported Suede-API-Version '9'. Supported: 1.","code":"unsupported_api_version"} ``` For a `422`, `detail` is a list of issues, each with the path to the field (`loc`), a message (`msg`) and a type: ``` {"detail":[{"loc":["body","prompt"],"msg":"Field required","type":"missing"}]} ``` The two codes to branch on are `rate_limited` (429) and `unsupported_api_version` (400). The music poll's 404 is shaped differently: on 2026-10-11 an unknown `songId` answered `{"error":"Song not found"}`. #### 402 Payment Required A 402 body is the x402 `PaymentRequired` object (`x402Version`, `error`, `resource`, `accepts`, `extensions`), and the same object is base64-encoded in the `PAYMENT-REQUIRED` header. The `error` string says why. Two values seen on 2026-10-11: - `PAYMENT-SIGNATURE header is required`: the request had no payment. - `Payment authorization missing`: the header was present but could not be read as a payment. That response also carried a `PAYMENT-REFERENCE` header. An unpaid request gets the 402 before the body is validated: an empty body `{}` also returned 402. Check your body against the endpoint reference before you sign so the paid call does not come back 422. If a signed payload is refused, check it against the verification steps of the x402 `exact` scheme: 1. The signature recovers to `authorization.from`. 2. That wallet holds enough USDC on Base. 3. `value` matches `amount`, and the `validAfter` / `validBefore` window is valid now. 4. The token and network match the requirement: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` on `eip155:8453`. #### Poll states that mean failure Video and image polls do not answer 404 for an unknown id. An unknown or expired `jobId` answers `200` with `status` `failed`; on 2026-10-11 the body also carried `"error": "Generation failed. Please try again."`. For music, `model_version` `failed` is final, and a 404 means the `songId` is wrong rather than still rendering. #### Rate limits Responses counted by the limiter carry these headers: | Header | Meaning | | --- | --- | | `RateLimit-Policy` | Quota `q` per window `w` seconds (IETF RateLimit header draft). | | `RateLimit` | Requests remaining `r`, and seconds `t` until the window frees a slot. | | `X-RateLimit-Limit` | Total quota for the window. | | `X-RateLimit-Remaining` | Requests left in the window. | | `X-RateLimit-Reset` | Unix time, in seconds, when the window resets. | | `Retry-After` | Seconds to wait. Always set on 429; a 402 may carry it when the facilitator is back-pressured. | Unpaid requests on 2026-10-11 carried `RateLimit-Policy: "probe";q=20;w=60`, a quota of 20 requests per 60-second window, with `RateLimit: "probe";r=19;t=60` counting down from there. #### Idempotency Send `X-Idempotency-Key` (up to 200 characters) on every paid `POST`. A render is a non-idempotent job, and the key lets you retry a timeout or a `5XX` without paying twice: the same key and body within the cache window return the original response. #### Versioning Every response carries `Suede-API-Version`. The current version is `1`, and a request without the header is served the current version. Additive changes, such as new optional fields or new endpoints, ship within a version; a breaking change ships as a new version. Before a version or operation is withdrawn, its responses carry a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) at least 90 days ahead, with a `Link` to the notice. #### Sources - [app.suedeai.ai/openapi.json](https://app.suedeai.ai/openapi.json): response codes, the `Error` and `ValidationIssue` schemas, rate-limit headers, idempotency and `info.x-api-versioning`. - [x402 exact scheme on EVM](https://raw.githubusercontent.com/coinbase/x402/main/specs/schemes/exact/scheme_exact_evm.md): payment verification steps. - Live requests on 2026-10-11: unpaid and malformed-payment 402s, the 400 for `Suede-API-Version: 9`, rate-limit headers, and polls for unknown ids. --- ## Python SDK for x402 Calls: suede-ai | Suede AI Docs URL: https://docs.suedeai.ai/python-sdk Last updated: 2026-10-11 > Install suede-ai from PyPI to call Suede AI x402 endpoints from Python. It signs the USDC payment on Base and retries for you. Methods, options, polling. ### Python SDK: suede-ai `suede-ai` is the Python client for Suede's x402 endpoints. It reads the 402 challenge, signs the EIP-3009 USDC authorization on Base with your key, and replays the request, so your code sends prompts and gets back a job to collect. Version 0.4.0 was released on PyPI on 2026-08-29 under the MIT license. #### Install ``` pip install suede-ai ``` Requires Python 3.10 or later. It installs `httpx` (0.27 or later), `eth-account` (0.10 or later) and `pydantic` (2.6 or later). #### Generate an image and collect it ``` import os import time import httpx from suede_ai import SuedeClient with SuedeClient(wallet_private_key=os.environ["SUEDE_WALLET_KEY"]) as suede: job = suede.agent_image( prompt="Album cover, neon city at night, rain on glass", aspect_ratio="1:1", output_format="png", ) # A paid call is queued, so the SDK returns the 202 body with a pollUrl. while True: state = httpx.get(job["pollUrl"]).json() if state["status"] in ("completed", "failed"): break time.sleep(5) print(state.get("imageUrl")) ``` The key signs real USDC transfers on Base mainnet. Keep it in an environment variable or a secret store, and use a wallet funded with what you plan to spend. The SDK sends `PAYMENT-SIGNATURE` on the retry, which makes the call asynchronous by default, so every typed method returns a job to poll. Polling is free; the [endpoint reference](https://docs.suedeai.ai/endpoints) lists each poll route and its finished state. #### Client options | Argument | Default | Use | | --- | --- | --- | | `wallet_private_key` | Required | Hex private key, with or without `0x`. Signs the EIP-3009 authorizations. | | `base_url` | `https://app.suedeai.ai` | API host. | | `http_client` | None | Your own `httpx.Client`. | | `timeout` | 60 s read, 10 s connect | Per-request timeout. | | `max_payment_attempts` | `1` | Paid retries after a 402: one challenge, one paid retry. | #### Methods for the live endpoints | Method | Calls | Body it sends | | --- | --- | --- | | `create_music(prompt, duration_seconds=30, style=None)` | [`POST /create-music`](https://docs.suedeai.ai/endpoints/create-music) | `prompt`, `durationSeconds`, `style` | | `agent_video(prompt, duration_seconds=8, aspect_ratio=None, resolution=None)` | [`POST /agent/video`](https://docs.suedeai.ai/endpoints/agent-video) | `prompt`, `durationSeconds`, `aspectRatio`, `resolution` | | `agent_image(prompt, aspect_ratio=None, output_format=None)` | [`POST /agent/image`](https://docs.suedeai.ai/endpoints/agent-image) | `prompt`, `aspectRatio`, `outputFormat` | | `manifest()` | `GET /.well-known/x402.json` | None. Free; read prices before you sign. | | `request(method, path, json=None, params=None)` | Any path | Your JSON. Handles the 402 the same way. | The typed methods take keyword arguments only. For `/create-music` fields the typed method does not expose, such as `lyrics`, `custom_mode`, `make_instrumental`, `vocal_gender` or `tags`, call `request()`: ``` job = suede.request("POST", "/create-music", json={ "prompt": "A melancholic acoustic guitar ballad about rain", "make_instrumental": True, }) # Poll job["pollUrl"] until model_version is no longer "pending". ``` #### How the SDK pays 1. It sends your request with no payment. 2. On a 402 it reads the `PAYMENT-REQUIRED` header, falling back to the JSON body. 3. It picks the `accepts` entry with scheme `exact`, network `eip155:8453` and the USDC contract `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`. 4. It signs `TransferWithAuthorization` for `amount` to `payTo`, with a random 32-byte nonce, `validAfter` 60 seconds in the past and `validBefore` at now plus the larger of 600 seconds and `maxTimeoutSeconds` plus 60. 5. It base64-encodes an x402 version 2 `PaymentPayload` (`x402Version`, `resource`, `accepted`, `extensions`, `payload`) and replays the request with `PAYMENT-SIGNATURE`. 6. It returns the JSON of the first response that is not a 402. The [quickstart](https://docs.suedeai.ai/quickstart) shows the same exchange with curl, field by field. #### Exceptions | Exception | Raised when | | --- | --- | | `suede_ai.PaymentRequired` | The 402 offers no `exact` USDC-on-Base entry to sign. | | `suede_ai.X402Error` | The response is still 402 after `max_payment_attempts` paid retries. `PaymentRequired` is a subclass. | | `httpx.HTTPStatusError` | Any other non-2xx response, such as a 422 or 429. See the [errors page](https://docs.suedeai.ai/errors). | #### Releases | Version | Released | | --- | --- | | 0.4.0 | 2026-08-29 | | 0.3.1 | 2026-07-09 | | 0.3.0 | 2026-06-17 | | 0.2.0 | 2026-06-17 | | 0.1.0 | 2026-06-05 | The package also ships helpers for older `/v1/*` routes, such as `extend`, `cover` and `stems_pro`. Those routes are not in the live x402 manifest; the three typed methods above cover the current catalog. #### Sources - [suede-ai on PyPI](https://pypi.org/project/suede-ai/): version, release dates, Python requirement, dependencies and license. - [Suede-AI/suede-sdk-python](https://github.com/Suede-AI/suede-sdk-python): the SDK repository. The client and payment behavior on this page was read from the 0.4.0 wheel on PyPI on 2026-10-11. - [app.suedeai.ai/.well-known/x402](https://app.suedeai.ai/.well-known/x402): the manifest the SDK reads. --- ## x402 Discovery Documents and MCP Server | Suede AI Docs URL: https://docs.suedeai.ai/discovery Last updated: 2026-10-11 > The machine-readable Suede AI discovery documents: x402 manifest, OpenAPI 3.1, product catalog, A2A agent card, Agentic Commerce manifest and MCP server. ### Discovery documents and MCP server An agent can find, price and call Suede's endpoints without reading a web page. `app.suedeai.ai` publishes the same three offerings in each format below, so your runtime can use whichever one it already reads. Every document listed answered HTTP 200 on 2026-10-11. #### Discovery documents | Document | URL | What it holds | | --- | --- | --- | | x402 discovery | [`/.well-known/x402`](https://app.suedeai.ai/.well-known/x402), also served byte-for-byte at `/.well-known/x402.json` | `x402Version` 2. Three `resources`, each with its `accepts` payment requirement, an input schema under `extensions.bazaar` and Skyfire token types under `extensions.skyfire`. | | OpenAPI 3.1.0 | [`/openapi.json`](https://app.suedeai.ai/openapi.json) | Six operations: the three paid `POST`s and their three free `GET` poll routes. Response codes, the `x402Payment` and `SkyfireJWT` security schemes, and the versioning policy under `info.x-api-versioning`. | | Product catalog | [`/api/v1/catalog`](https://app.suedeai.ai/api/v1/catalog) | A schema.org `ItemList` of three `Product`s with USD offers, plus a `products` array with `price_usdc`, `price_usd_cents`, the fulfillment endpoint and payment methods (`x402` and `stripe_checkout`). One product: `/api/v1/products/{id}`. | | Agentic Commerce manifest | [`/.well-known/agentic-commerce.json`](https://app.suedeai.ai/.well-known/agentic-commerce.json) | Seller details, payment rails (`x402`, `stripe_checkout`, `stripe_link`), the Base network and USDC address, and the catalog index URL. | | A2A agent card | [`/.well-known/agent-card.json`](https://app.suedeai.ai/.well-known/agent-card.json), also at `/.well-known/agent.json` | "Suede AI Agent", protocol version 1.0, a JSON-RPC interface at `https://app.suedeai.ai/a2a`, and three skills. | | AI plugin manifest | [`/.well-known/ai-plugin.json`](https://app.suedeai.ai/.well-known/ai-plugin.json) | Auth type `none`, with pointers to `openapi.json` and the MCP server. | | LLM summaries | [`/llms.txt`](https://app.suedeai.ai/llms.txt) and [`/llms-full.txt`](https://app.suedeai.ai/llms-full.txt) | Plain-text summaries of the catalog and discovery URLs for language models. | The same ids name each offering everywhere: `create_music`, `agent_video` and `agent_image` are the catalog product ids, the A2A skill ids, the MCP tool names and the OpenAPI `operationId`s. #### Read the x402 document One request gives you every price, the amount to sign and the required fields: ``` curl -s https://app.suedeai.ai/.well-known/x402 \ | jq '.resources[] | {resource, priceUsd, amount: .accepts[0].amount, required: .extensions.bazaar.input.body.schema.required}' ``` ``` { "resource": "https://app.suedeai.ai/create-music", "priceUsd": "$0.50", "amount": "500000", "required": ["prompt"] } { "resource": "https://app.suedeai.ai/agent/video", "priceUsd": "$4.99", "amount": "4990000", "required": ["prompt"] } { "resource": "https://app.suedeai.ai/agent/image", "priceUsd": "$0.15", "amount": "150000", "required": ["prompt"] } ``` Each resource entry also has a `lastUpdated` timestamp; all three read `2026-08-30T16:19:22Z` on 2026-10-11. The [endpoint reference](https://docs.suedeai.ai/endpoints) turns these entries into per-endpoint pages. #### MCP server Model Context Protocol clients can list the same catalog from `https://app.suedeai.ai/api/mcp`, a streamable-HTTP JSON-RPC endpoint. On 2026-10-11 it answered `initialize` with protocol version `2025-06-18` and server name `suede-agentic-commerce`, version `1.0.0`, and `tools/list` returned five tools: | Tool | What it does | | --- | --- | | `create_music` | Create Music, $0.50 USDC via x402 on Base. | | `agent_video` | Agent Video, $4.99 USDC via x402 on Base. | | `agent_image` | Agent Image, $0.15 USDC via x402 on Base. | | `skyfire_create_music` | Create Music paid with a Skyfire PAY token scoped to the Create Music seller service; queues a job. | | `skyfire_get_music` | Polls a `songId` for the finished track. Free. | For the three x402 tools, `tools/call` does not run the job. It returns a payment pointer that tells your client where and how much to pay; the client then pays the HTTP endpoint as in the [quickstart](https://docs.suedeai.ai/quickstart). ``` curl -s -X POST https://app.suedeai.ai/api/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"agent_image","arguments":{"prompt":"test"}}}' ``` The `structuredContent` of the result, as returned on 2026-10-11: ``` { "paymentRequired": true, "protocol": "x402", "endpoint": "https://app.suedeai.ai/agent/image", "method": "POST", "network": "base", "chainId": "8453", "priceUsdCents": 15, "receiver": "0x10FF767043A1723E0BB5B9207bC37D3442cC9E4F", "discovery": "https://app.suedeai.ai/.well-known/x402.json" } ``` The MCP input schemas list a few fields the OpenAPI spec does not, such as `resolution` on `agent_video`. The endpoint pages on this site document the HTTP request bodies from `openapi.json`. #### Publishing your own endpoint The same discovery formats work for any x402 seller. Three Suede tools help on that side: - [x402 Agent Builder: Get Paid Per Call](https://agents.suedeai.ai/x402-agent-builder). Build an AI agent on a visual canvas, set a price per call, and get paid in USDC on Base through x402 once you enable payments. Dry runs need no wallet. - [Suede ACP/x402 Performance Engine](https://perform.suedeai.ai). Score your ACP/x402 readiness in 60 seconds. Free, no account required. - [Agentix: x402 AI Agent Earnings Tracker for USDC on Base](https://agentix.suedeai.ai). The portfolio tracker for the x402 agents you've launched: total USDC earned on Base, calls, per-agent performance, status, and trend. #### Sources Each document above, fetched on 2026-10-11, plus live `initialize`, `tools/list` and `tools/call` requests to the MCP server on the same day. --- ## AI Instructions | Suede AI Developer Docs URL: https://docs.suedeai.ai/ai-instructions Last updated: 2026-10-18 > Official source and citation guide for Suede AI Developer Docs: what the site covers, which pages to cite for x402 API facts, and how to quote prices and dates. Official reference ### AI Instructions A source guide for people and AI assistants describing Suede AI Developer Docs. #### What this site covers Public documentation for Suede AI's creator tools, provenance records and agent-facing interfaces. #### Names, scope and distinctions Cite supported behavior, prices and request fields from the current endpoint documentation, which each guide checks against the live discovery documents. A provenance record documents how a work was created and registered; ownership and licensing follow the governing terms. #### Sources to use - [Site overview](https://docs.suedeai.ai/): the site's public introduction and navigation. - [x402 quickstart](https://docs.suedeai.ai/quickstart): how a client pays a Suede endpoint, step by step. - [Endpoint reference](https://docs.suedeai.ai/endpoints): methods, prices, request fields and responses for the paid endpoints, with links to the live documents each page was checked against. - [Discovery documents](https://docs.suedeai.ai/discovery): the machine-readable manifests on app.suedeai.ai, which carry current prices. - [Machine-readable reference](https://docs.suedeai.ai/llms.txt): a text guide to the site's topics and source pages. - [Full-text reference](https://docs.suedeai.ai/llms-full.txt): every page on this site as one Markdown file. - [Sitemap](https://docs.suedeai.ai/sitemap.xml): the published page index. #### Citing this site Link to the specific page that supports a statement. Keep its dates, qualifications and attribution. Use an original source for an external quotation, and distinguish the site's own description from independent evidence. Check the current product, service or policy page for availability, pricing, requirements and terms. Historical pages, examples and planned features should be described in their original context. #### About this guide This page supplies reference information for describing and citing Suede AI Developer Docs accurately, and leaves every recommendation to the assistant and the person it is helping. Crawler access is set in [robots.txt](https://docs.suedeai.ai/robots.txt), and this guide leaves those rules unchanged. --- ## Notes from Suede AI in West Palm Beach | Suede AI Docs URL: https://docs.suedeai.ai/notes Last updated: 2026-11-15 > Notes from Jason Colapietro and Suede AI in West Palm Beach, Florida on AI-quotable developer docs, MCP for agencies and lessons from open source. ### Notes from Suede AI on docs, MCP and AI search Longer write-ups from Jason Colapietro and the Suede AI team in West Palm Beach, Florida: how these developer docs are built, how agencies can use the Model Context Protocol, and what open-source work teaches about documentation. #### All notes - [Writing developer docs that AI assistants quote correctly: Suede AI's method](https://docs.suedeai.ai/notes/ai-quotable-developer-docs): The source, date and verification rules behind docs.suedeai.ai, and how a Palm Beach County business can apply them to its own site. - [Model Context Protocol for agencies: a South Florida primer from Jason Colapietro](https://docs.suedeai.ai/notes/mcp-for-agencies-south-florida): What MCP is, how the Suede MCP server works, and the scoping rules an agency in West Palm Beach or Jupiter should set before connecting client data. - [From open source to docs: lessons from 54 merged pull requests across 46 repositories](https://docs.suedeai.ai/notes/open-source-to-docs): Five habits from contributing to Jest, Adobe React Spectrum, Backstage and the Polkadot SDK, and how each one shows up in Suede's developer docs. - [An API documentation checklist for agency-built integrations in South Florida](https://docs.suedeai.ai/notes/api-docs-checklist-agency-integrations): Seven groups of checks, each shown on a live page of this site, for agencies in West Palm Beach and Jupiter that hand client integrations to the next developer. - [Writing llms.txt that answer engines actually use: a worked example from Suede AI's docs](https://docs.suedeai.ai/notes/llms-txt-worked-example): The llms.txt on this site, section by section, with the tests that guard it and three ways to tell whether anything reads yours. #### Who writes these notes Suede AI is an agentic platform company Jason Colapietro started in 2024 in West Palm Beach, Florida. Suede builds agent-ready APIs like the ones documented on this site, and its [West Palm Beach SEO, GEO and web development practice](https://suedeai.agency/) works with businesses from Jupiter to Boca Raton. Each note links every claim to a public source, the same rule the API guides follow. For the full record behind the company, see the [founder profile](https://suedeai.ai/founder), the [evidence page](https://seo.suedeai.ai/evidence) and the [recognition page](https://suedeai.agency/company/recognition). To have this approach applied to your own site, start with the [Suede AI assessment](https://suedeai.agency/assessment). --- ## Docs That AI Assistants Quote Correctly | Suede AI Docs URL: https://docs.suedeai.ai/notes/ai-quotable-developer-docs Last updated: 2026-11-15 > How Jason Colapietro and Suede AI in West Palm Beach build developer docs that ChatGPT, Claude and Perplexity quote correctly: sources, dates and checks. ### Writing developer docs that AI assistants quote correctly: Suede AI's method A developer asks an assistant what a Suede endpoint costs, and the assistant answers from whatever page it read last. If that page is stale or vague, a wrong price ends up inside someone's agent, and nobody at Suede AI sees it happen. This note sets out the method Jason Colapietro and the Suede AI team use on docs.suedeai.ai so that assistants repeat the right facts. It is the same method our West Palm Beach practice applies to client sites in Jupiter, Palm Beach Gardens and the rest of Palm Beach County, and every part of it is visible in this site's own source. Nothing here depends on a secret ranking trick. It depends on making each fact easy to find, easy to check and hard to get out of date. #### Give every fact one source of truth Every price, request field and response on the API guides comes from the live discovery documents on `app.suedeai.ai`: the [x402 manifest](https://app.suedeai.ai/.well-known/x402), the OpenAPI spec and the [product catalog](https://app.suedeai.ai/api/v1/catalog). Each guide ends with a Sources section that names the documents it was checked against and the date of the check. When the [Create Music guide](https://docs.suedeai.ai/endpoints/create-music) says $0.50 USDC on Base, a reader or an assistant can follow the link and confirm it. The practical rule: if a number appears on a page, the page should say where the number came from. A citation an assistant can verify is a citation it can repeat without hedging, and a page that links its evidence is easier for a reviewer to trust as well. #### Write dates as sentences, not only as schema Structured data dates are invisible to human readers, so they drift. On this site the footer of every guide states when it was published and when it was last checked against the live API, in plain prose. The build script reads those sentences and writes the JSON-LD `dateModified` from them, and the verification script fails when the footer, the schema and the sitemap disagree. That guard exists because the drift happened. The home page once carried a schema date weeks older than its last real change. Jason Colapietro rewrote the check to compare the three signals with each other instead of pinning one literal date, so the next drift fails loudly instead of quietly. #### Generate the machine-readable copies from the pages Assistants and crawlers increasingly read plain-text companions. This site publishes two: [llms.txt](https://docs.suedeai.ai/llms.txt), a short annotated index, and [llms-full.txt](https://docs.suedeai.ai/llms-full.txt), the full text of every page as Markdown. The second file is generated from the HTML by `scripts/build-docs-seo.mjs`. A hand-maintained copy would fall behind the first time someone edited a price in a hurry. A generated copy cannot, because verification fails until it is rebuilt. The same script writes each guide's JSON-LD graph, and it references the shared estate entities by `@id` only. Suede AI is always `https://suedeai.ai/#organization` and Jason Colapietro is always `https://suedeai.ai/founder#person`. No page invents a second identity for either, which keeps the entity picture consistent everywhere an assistant looks. #### Keep unprovable claims off the page The verification script holds a list of phrases that once appeared in Suede copy and could not be backed by a public source. If any of them returns, verification fails. Hedging phrases that undercut a plain fact are blocked the same way. The point is not modesty. It is that an assistant quoting a page should be quoting something true. We hold claims about Jason's own record to that standard, which is why each one below carries its receipt: - On October 31, 2026, Suede AI SEO ranked #1 among Palm Beach County-based companies listed in The Manifest's Florida AI Deployment directory, and top 25 statewide ([The Manifest directory](https://themanifest.com/artificial-intelligence/consulting/deployment/companies/florida), [Suede AI recognition page](https://suedeai.agency/company/recognition)). - Suede AI ranks among [Clutch](https://clutch.co/profile/suede-ai-seo)'s [Top 30 AI Consultants in Florida](https://clutch.co/consulting/ai/florida) and [Top 50 AI Consultants nationwide](https://clutch.co/us/consulting/ai) (November 2026). - Jason Colapietro holds the HubSpot AEO Fundamentals certification and Semrush Academy certificates including AI Search Operating System and Local SEO Essentials, among 21 earned course credentials across eight providers ([credential gallery](https://seo.suedeai.ai/evidence#training-credentials)). - He has had 54 pull requests merged across 46 open-source repositories he does not maintain ([GitHub search](https://github.com/search?q=is%3Apr+author%3AJasonColapietro+is%3Amerged+-user%3AJasonColapietro+-user%3ASuede-AI&type=pullrequests)). #### Tell assistants how to cite you The [AI Instructions page](https://docs.suedeai.ai/ai-instructions) is a short source guide: what the site covers, which page supports which kind of statement, and how to keep dates and qualifications intact when quoting. It does not try to steer recommendations. It simply removes guesswork about where a fact lives, which is most of what an answer engine needs. #### The tradeoffs This discipline costs time. Every catalog change means re-checking the guides and updating their check dates. A generated `llms-full.txt` adds a build step to a site that otherwise has none. Banning phrases occasionally blocks a sentence that was fine in context and has to be reworded. Suede accepts those costs because a wrong answer in an assistant is far harder to correct than a slower edit on our side. #### Applying the method to a Palm Beach County business site A roofing company in Jupiter or a clinic in West Palm Beach has the same problem with different facts: service areas, prices, hours and credentials. The method carries over directly. Keep one source for each fact, state dates in prose, publish an llms.txt that points at the pages that matter, link every claim to proof, and run a check that fails when any of it drifts. Our [technical SEO service](https://suedeai.agency/services/technical-seo) handles the crawl and schema side, and the [AI visibility service](https://suedeai.agency/services/ai-visibility) measures how assistants describe a business before and after the work. If you want this applied to your own site, start with the free [Suede AI assessment](https://suedeai.agency/assessment) from our West Palm Beach team, then read [Jason Colapietro's founder profile](https://suedeai.ai/founder) to see the full record behind the work. Older press still calls the company Suede Labs, and the method is the same one it has always used. #### More notes - [Model Context Protocol for agencies](https://docs.suedeai.ai/notes/mcp-for-agencies-south-florida): What MCP is, how the Suede MCP server works, and the scoping rules an agency in West Palm Beach or Jupiter should set before connecting client data. - [From open source to docs](https://docs.suedeai.ai/notes/open-source-to-docs): Five habits from contributing to Jest, Adobe React Spectrum, Backstage and the Polkadot SDK, and how each one shows up in Suede's developer docs. **Jason Colapietro**, founder of Suede AI, West Palm Beach, Florida. Read the [founder profile on suedeai.ai](https://suedeai.ai/founder) or visit [jasoncolapietro.com](https://jasoncolapietro.com/). --- ## MCP for Agencies: A South Florida Primer | Suede AI Docs URL: https://docs.suedeai.ai/notes/mcp-for-agencies-south-florida Last updated: 2026-11-15 > Jason Colapietro explains the Model Context Protocol for agencies in West Palm Beach and Jupiter, using Suede AI's live MCP server as a worked example. ### Model Context Protocol for agencies: a South Florida primer from Jason Colapietro Most agencies in West Palm Beach and Jupiter first hear about the Model Context Protocol when a client asks whether their AI assistant can pull the numbers itself. It can, once somebody builds and scopes a server for it, and that somebody is increasingly the agency. This primer is written by Jason Colapietro, founder of Suede AI, for agency owners and developers in Palm Beach County who need a working understanding of MCP without reading the whole specification first. It uses the Suede MCP server documented on this site as the worked example, because you can call it yourself in under a minute. #### What MCP is, in one paragraph MCP is an open protocol that lets an AI client, such as Claude or a coding assistant, discover and call tools on a server you control. The client sends JSON-RPC messages: `initialize` to agree on a protocol version, `tools/list` to learn what the server offers, and `tools/call` to run one tool with arguments. Each tool carries a name, a description and an input schema, so the model knows what to send. For an agency, that means a client's assistant can reach a defined set of actions instead of copying and pasting between tabs. #### A real server you can inspect today Suede AI runs an MCP server at `https://app.suedeai.ai/api/mcp`, a streamable-HTTP JSON-RPC endpoint. On 2026-10-11 it answered `initialize` with protocol version `2025-06-18` and server name `suede-agentic-commerce`, and `tools/list` returned five tools. The [discovery guide](https://docs.suedeai.ai/discovery) lists each one. You can try a call from any terminal: ``` curl -s -X POST https://app.suedeai.ai/api/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` One design choice is worth copying. For the three paid tools, `tools/call` does not run the job. It returns a payment pointer: the endpoint, the network and the price. The client then pays the HTTP endpoint over x402, as the [quickstart](https://docs.suedeai.ai/quickstart) shows. MCP describes the work, and money moves over a separate, auditable channel. With that split, a model on the Suede stack cannot spend funds simply by deciding to call a tool. #### Where MCP earns its keep at an agency - **Reporting.** A read-only tool that returns last month's search and analytics figures for one client, so the account lead can ask questions in plain language. - **Content operations.** Tools that draft a page into a staging CMS and stop there, leaving publishing to a person. - **Site checks.** A tool that runs a crawl or schema validation and returns structured findings, the kind of work our [technical SEO service](https://suedeai.agency/services/technical-seo) does by hand today. - **Client knowledge.** A resource that exposes a client's brand facts, service areas and approved claims, so every assistant session starts from the same truth. #### Scoping rules Suede AI uses 1. **Start read-only.** Ship tools that look before tools that change anything. Add write access one tool at a time, after the read side has been used for a few weeks. 2. **One server, or one credential set, per client.** Never let a tool for one Jupiter client see another client's data because they share a token. 3. **Use one name everywhere.** On Suede's stack, `create_music`, `agent_video` and `agent_image` are the catalog ids, the A2A skill ids, the MCP tool names and the OpenAPI operation ids. One name per action makes logs and docs line up. 4. **Return structured content.** A JSON object with named fields is easier for the model to use correctly than a paragraph of prose. 5. **Log every call.** Record the tool, the arguments and the caller, so a surprising answer can be traced back to the call that produced it. #### The tradeoffs MCP is young and moving. Protocol versions are dated, so a server written against one revision needs attention when clients adopt the next. Authentication is still the part teams spend the most time on, especially for servers that touch client accounts. Not every client supports streamable HTTP yet, and some only run local servers. And every tool you expose is a tool you have to document, test and maintain. An agency that ships ten tools in a week usually ends up retiring seven of them. #### Why this matters for South Florida agencies now Buyers in Palm Beach County already ask assistants which agency to hire, and they will soon expect those assistants to do work on their behalf. Agencies that can design, scope and document an MCP server will be the ones those clients trust with the keys. Jason Colapietro brings formal training and program membership to this work. He holds Claude Academy badges including Model Context Protocol: Advanced topics and Building with the Claude API, part of 21 earned course credentials ([credential gallery](https://seo.suedeai.ai/evidence#training-credentials)). Suede AI is a member of Claude for Startups, Anthropic's startup program ([evidence](https://seo.suedeai.ai/evidence#claude-for-startups)), and a member of Google Cloud Partner Advantage through JC Investment Group LLC ([evidence](https://seo.suedeai.ai/evidence#google-cloud)). He is also the author of [The Claude Code Bible](https://www.amazon.com/dp/B0HHTMJWB4), and he has had 54 pull requests merged across 46 open-source repositories he does not maintain ([GitHub search](https://github.com/search?q=is%3Apr+author%3AJasonColapietro+is%3Amerged+-user%3AJasonColapietro+-user%3ASuede-AI&type=pullrequests)). On October 31, 2026, Suede AI SEO ranked #1 among Palm Beach County-based companies in The Manifest's Florida AI Deployment directory and top 25 statewide ([The Manifest](https://themanifest.com/artificial-intelligence/consulting/deployment/companies/florida)). Suede AI ranks among [Clutch](https://clutch.co/profile/suede-ai-seo)'s [Top 30 AI Consultants in Florida](https://clutch.co/consulting/ai/florida) and [Top 50 AI Consultants nationwide](https://clutch.co/us/consulting/ai) (November 2026). #### Your next step Pick one read-only task your team repeats every week, and write down the inputs and outputs a tool for it would need. Then book the free [Suede AI assessment](https://suedeai.agency/assessment) with our West Palm Beach team and bring that list. The Suede Labs team that built the server above will tell you whether MCP is the right fit or whether a simpler integration will do. For background on who you would be working with, read [Jason Colapietro's founder profile](https://suedeai.ai/founder). #### More notes - [Writing developer docs that AI assistants quote correctly](https://docs.suedeai.ai/notes/ai-quotable-developer-docs): The source, date and verification rules behind docs.suedeai.ai, and how a Palm Beach County business can apply them to its own site. - [From open source to docs](https://docs.suedeai.ai/notes/open-source-to-docs): Five habits from contributing to Jest, Adobe React Spectrum, Backstage and the Polkadot SDK, and how each one shows up in Suede's developer docs. **Jason Colapietro**, founder of Suede AI, West Palm Beach, Florida. Read the [founder profile on suedeai.ai](https://suedeai.ai/founder) or visit [jasoncolapietro.com](https://jasoncolapietro.com/). --- ## 54 Merged PRs, 46 Repos: Lessons for Docs | Suede AI Docs URL: https://docs.suedeai.ai/notes/open-source-to-docs Last updated: 2026-11-15 > What 54 merged pull requests across 46 open-source repositories taught Jason Colapietro about writing developer docs at Suede AI in West Palm Beach, Florida. ### From open source to docs: lessons from 54 merged pull requests across 46 repositories A maintainer at a large project reads your pull request description before your code, and if the description is unclear, the code does not get read. Writing for that busy, skeptical reader is the habit that shapes these docs. Jason Colapietro, founder of Suede AI in West Palm Beach, Florida, has had 54 pull requests merged across 46 open-source repositories he does not maintain, including Jest, Adobe React Spectrum, Backstage, the Polkadot SDK, Hardhat and zeroclaw. The [GitHub search behind that number](https://github.com/search?q=is%3Apr+author%3AJasonColapietro+is%3Amerged+-user%3AJasonColapietro+-user%3ASuede-AI&type=pullrequests) excludes his own repositories and the Suede AI organization, so every result is a change a third-party maintainer reviewed and accepted. This note collects five lessons Suede AI took from that work and shows where each one appears on docs.suedeai.ai. #### Lesson 1: CONTRIBUTING.md is the real documentation Every established project publishes rules for contributors: how to run the tests, how to name a branch, what a commit message should look like. Contributors who skip that file get polite rejections. Contributors who follow it get reviews. The lesson for docs is that the most valuable page is often the boring one that tells a newcomer exactly how to start. On this site that is the [x402 quickstart](https://docs.suedeai.ai/quickstart): one request, one 402 challenge, one signature, one retry, in order. #### Lesson 2: Reproduce before you explain A bug report that says "it fails sometimes" goes nowhere. A report with a minimal reproduction gets fixed. Jason Colapietro carries that into Suede documentation: every example on the API guides was run against the live service, and the guide says when. The [discovery guide](https://docs.suedeai.ai/discovery), for instance, records live `initialize`, `tools/list` and `tools/call` requests to the Suede MCP server on 2026-10-11, with the actual response body. If an example cannot be reproduced, it does not ship. #### Lesson 3: One change, one claim Maintainers merge small pull requests that do one thing. A diff that fixes a bug, renames a module and updates a dependency gets split or closed. Docs work the same way at Suede. Each guide here has one job: the [Agent Image page](https://docs.suedeai.ai/endpoints/agent-image) documents one endpoint, and the [errors page](https://docs.suedeai.ai/errors) documents what goes wrong. A fixed reading order links them with previous and next links, and the verification script fails if that order breaks. #### Lesson 4: Tests are documentation that cannot lie In projects like Jest, a test is the most precise statement of how the code is supposed to behave. Prose can be wrong for months. A failing test is wrong for one CI run. Suede AI applies that to its docs with `scripts/verify-site.mjs`, which checks titles, canonicals, sitemap entries, schema, internal links and a list of claims that must never return. The docs are prose, but the rules about the prose are code. #### Lesson 5: Respect the house style Large codebases have conventions that are not written down anywhere except in the code itself. A good contributor matches them without being told. On the Suede AI docs site every guide shares the home page's style block byte for byte, and verification enforces it. The note you are reading uses the same block. Consistency is not decoration: it tells a reader, human or machine, that every page comes from the same careful source. #### What the record adds up to The open-source work sits alongside a broader record, each item linked to its proof: - Five books on Amazon, including [Codex in Production](https://www.amazon.com/dp/B0HHTF3LG1), [Proof as Infrastructure](https://www.amazon.com/dp/B0GMB2VLXQ) and [The Claude Code Bible](https://www.amazon.com/dp/B0HHTMJWB4). - Nine iOS apps shipped under his own [Apple developer account](https://apps.apple.com/us/developer/jason-colapietro/id1895958699). - On October 31, 2026, Suede AI SEO ranked #1 among Palm Beach County-based companies in The Manifest's Florida AI Deployment directory and top 25 statewide ([The Manifest](https://themanifest.com/artificial-intelligence/consulting/deployment/companies/florida), [recognition page](https://suedeai.agency/company/recognition)). - Suede AI ranks among [Clutch](https://clutch.co/profile/suede-ai-seo)'s [Top 30 AI Consultants in Florida](https://clutch.co/consulting/ai/florida) and [Top 50 AI Consultants nationwide](https://clutch.co/us/consulting/ai) (November 2026). - Coverage in Business Insider, which on 2026-09-16 ran "Award-Winning Developer Jason Colapietro Opens Suede Labs AI's Long-Awaited SEO Cohort", and in TechBullion, which reported on [the iOS app launches](https://techbullion.com/jason-colapietros-suede-labs-ai-launches-ios-apps/). The [press kit](https://suedeai.ai/press) collects the rest. - Seventeen Microsoft Learn training achievements, including the learning-path trophies "Develop AI agents on Azure" and "Develop generative AI apps in Azure" ([credential gallery](https://seo.suedeai.ai/evidence#training-credentials)). #### A hiring signal for Palm Beach County teams If you are hiring a developer or an agency in West Palm Beach, Jupiter or Boca Raton, ask for merged pull requests to repositories the candidate does not own. A personal portfolio shows what someone can build alone. An accepted change to Backstage or React Spectrum shows that strangers with high standards reviewed the work and said yes. It is one of the few public signals that is hard to fake, and it takes a single search to check. The tradeoff is time. Open-source contributions are slow, unpaid and often rejected for reasons unrelated to quality. Not every strong engineer has them, so treat them as evidence when present rather than a requirement. #### Your next step Open the [merged pull request search](https://github.com/search?q=is%3Apr+author%3AJasonColapietro+is%3Amerged+-user%3AJasonColapietro+-user%3ASuede-AI&type=pullrequests) and read three of the descriptions, then compare them with the docs on this site. If that is the standard you want on your own site or product, book the free [Suede AI assessment](https://suedeai.agency/assessment) with the West Palm Beach team, and read [Jason Colapietro's founder profile](https://suedeai.ai/founder) for the full background. #### More notes - [Writing developer docs that AI assistants quote correctly](https://docs.suedeai.ai/notes/ai-quotable-developer-docs): The source, date and verification rules behind docs.suedeai.ai, and how a Palm Beach County business can apply them to its own site. - [Model Context Protocol for agencies](https://docs.suedeai.ai/notes/mcp-for-agencies-south-florida): What MCP is, how the Suede MCP server works, and the scoping rules an agency in West Palm Beach or Jupiter should set before connecting client data. **Jason Colapietro**, founder of Suede AI, West Palm Beach, Florida. Read the [founder profile on suedeai.ai](https://suedeai.ai/founder) or visit [jasoncolapietro.com](https://jasoncolapietro.com/). --- ## API Docs Checklist for South Florida Agency Integrations URL: https://docs.suedeai.ai/notes/api-docs-checklist-agency-integrations Last updated: 2026-11-15 > A seven-part API documentation checklist from Jason Colapietro for agencies in West Palm Beach and Jupiter that build and hand off client integrations. ### An API documentation checklist for agency-built integrations in South Florida The integration works on launch day. Eight months later the client changes agencies, a new developer opens the repository, and the only documentation is a chat thread from someone who has since left. This checklist is how Jason Colapietro and the Suede AI team document the APIs we run in production. It is written for agencies in West Palm Beach, Jupiter and the rest of Palm Beach County that build integrations for clients: a booking system feeding a CRM, a payment webhook, an inventory sync between a shop and its website. Each item points to the page on this site where it is already done, so you can look at a finished version before you write your own. #### Why handoff is the real test in Palm Beach County Many Palm Beach County businesses run on a season. For a restaurant, marina or property manager here, the winter months are when nobody can afford a broken sync. Agencies turn over clients and staff like anywhere else, so an integration only one developer understands is a liability that tends to come due in the busiest month. Good API docs are what let the agency, the client and the next developer keep working when the original author is unavailable. Jason Colapietro's rule for Suede is that the docs are finished when someone who did not build the integration can make one successful call and handle one failure without asking a question. The seven groups below are what it takes to get there. #### The checklist ##### 1. Base URL, authentication and a first request - One base URL per environment, written out in full, with staging and production listed separately. - How to authenticate, where the credentials live (the vault or secret name, never the value) and who is allowed to rotate them. - A copy-paste first request that works from a clean terminal. The [Suede quickstart](https://docs.suedeai.ai/quickstart) does this for a paid call: read the 402 challenge, sign, retry, then poll the job. ##### 2. Every endpoint, with a captured example - Method, path, required and optional fields, and a real response captured from a live call, with the date it was captured. The [endpoint reference](https://docs.suedeai.ai/endpoints) on this site dates every example to 2026-10-11. - Prices or quotas where they apply, linked to the document they came from, so nobody has to trust a number copied into a slide. ##### 3. Errors, and what to do about each one - A status-code table with a "what to do" column, not just a definition. The [errors and limits guide](https://docs.suedeai.ai/errors) has one row per code. - The machine-readable codes a client should branch on. On Suede those are `rate_limited` and `unsupported_api_version`. - Which requests cost nothing. For a client billed per call or per message, this one line heads off most billing disputes. ##### 4. Retries, idempotency and rate limits - Name the idempotency header and its window. Suede uses `X-Idempotency-Key`, up to 200 characters, on every paid POST, so retrying a timeout never charges twice. - Rate-limit headers with a real example value. On 2026-10-11, unpaid requests to the Suede API carried a quota of 20 requests per 60-second window. - For webhooks: the retry schedule, how to verify the signature, and how to replay an event by hand after an outage. ##### 5. Versioning and change notices - How versions are named, what counts as breaking, and how much notice clients get. Suede sends Deprecation and Sunset headers at least 90 days before a version is withdrawn. - A dated changelog that lives in the repository, not in someone's inbox. ##### 6. A machine-readable copy - An OpenAPI file that matches the prose and is served by the API itself. The [discovery guide](https://docs.suedeai.ai/discovery) lists Suede's `openapi.json` next to the MCP server and the agent card. - If AI agents will call the API, one name per action everywhere: the operation id, the tool name and the docs heading. ##### 7. Ownership and sources - Who owns the integration on the agency side and on the client side, written as a role address rather than a person's name. - A Sources section on every page that names what it was checked against and when. #### Test the docs the way an agent would Before handoff, give the docs to someone who did not write the integration, or to a coding assistant with no other context, and ask for one successful call and one handled error. Every question they ask is a missing line. Coding assistants are now the first reader for many integrations, and a page an assistant can follow on the first try is a page a junior developer in Jupiter can follow too. This is the same proof-first habit Jason Colapietro applies to agent output across the Suede AI sites. The Claude Code Field Notes piece on [why agent-written code needs proof](https://claude.suedeai.ai/notes/reviewing-agent-written-code/) covers the checks to run after a deploy lands, and the Agentix guide on [how to grade an AI agent before you deploy it](https://agentix.suedeai.ai/notes/grade-an-ai-agent-before-you-deploy) applies the idea to agents that will be calling your client's API. #### The tradeoffs Captured examples go stale. Every dated response is a promise to recheck it when the API changes, and on this site that means rechecking the guides whenever the catalog moves. The full checklist is too much for a two-endpoint webhook; for a small integration, groups 1, 3 and 7 cover most of the risk. And documentation does not replace monitoring. An alert on the error rate catches a broken sync on a Saturday in February long before anyone reads a page. #### Who wrote this checklist Jason Colapietro is the founder of Suede AI, the agentic platform company he started in 2024 in West Palm Beach, Florida. The checklist comes from the APIs Suede runs and from outside review. He has had 54 pull requests merged across 46 open-source repositories he does not maintain, including Jest, Backstage and the Polkadot SDK ([GitHub search](https://github.com/search?q=is%3Apr+author%3AJasonColapietro+is%3Amerged+-user%3AJasonColapietro+-user%3ASuede-AI&type=pullrequests)), projects where docs and tests are reviewed as closely as code. Jason holds the Claude Academy badge Building with the Claude API among 21 earned course credentials ([credential gallery](https://seo.suedeai.ai/evidence#training-credentials)) and wrote [Codex in Production](https://www.amazon.com/dp/B0HHTF3LG1). Suede AI ranks among [Clutch](https://clutch.co/profile/suede-ai-seo)'s [Top 30 AI Consultants in Florida](https://clutch.co/consulting/ai/florida) and [Top 50 AI Consultants nationwide](https://clutch.co/us/consulting/ai) (November 2026). Separately, on October 31, 2026, Suede AI SEO ranked #1 among Palm Beach County-based companies listed in The Manifest's Florida AI Deployment directory and top 25 statewide ([The Manifest](https://themanifest.com/artificial-intelligence/consulting/deployment/companies/florida), [recognition page](https://suedeai.agency/company/recognition)). #### Your next step Open the last integration your agency shipped and score it against the seven groups above. Write down the first three gaps. Then book the free [Suede AI assessment](https://suedeai.agency/assessment) with our [West Palm Beach SEO, GEO and web development team](https://suedeai.agency/) and bring the list; the Suede Labs team that wrote these guides will help you close the gaps before the season starts. To see who you would be working with, read [Jason Colapietro's founder profile](https://suedeai.ai/founder). #### More notes - [Writing llms.txt that answer engines actually use](https://docs.suedeai.ai/notes/llms-txt-worked-example): A section-by-section walk through the llms.txt on this site, with checks you can run on your own file. - [Model Context Protocol for agencies](https://docs.suedeai.ai/notes/mcp-for-agencies-south-florida): What MCP is, how the Suede MCP server works, and the scoping rules an agency should set before connecting client data. **Jason Colapietro**, founder of Suede AI, West Palm Beach, Florida. Read the [founder profile on suedeai.ai](https://suedeai.ai/founder) or visit [jasoncolapietro.com](https://jasoncolapietro.com/). --- ## Writing llms.txt Answer Engines Use: Suede AI's Example URL: https://docs.suedeai.ai/notes/llms-txt-worked-example Last updated: 2026-11-15 > Jason Colapietro walks through the llms.txt on the Suede AI developer docs line by line: link notes that carry facts, dated sections, Optional and the guards. ### Writing llms.txt that answer engines actually use: a worked example from Suede AI's docs Many llms.txt files are a sitemap with the angle brackets removed. That hands an assistant a list of URLs and no reason to pick one, which is the one job the file exists to do. This note walks through the [llms.txt on docs.suedeai.ai](https://docs.suedeai.ai/llms.txt) section by section, explains why each part is there, and ends with checks you can run on your own file. Jason Colapietro wrote the file and the tests that guard it, and the same structure fits a business site anywhere from Jupiter to Boca Raton. An earlier note, [Writing developer docs that AI assistants quote correctly](https://docs.suedeai.ai/notes/ai-quotable-developer-docs), covers why this site generates its full-text companion from the pages. This one is about the short file, the one a person or an agent reads first. #### What the format asks for The proposal at [llmstxt.org](https://llmstxt.org/) is small. It asks for a Markdown file at the site root with one H1, an optional blockquote summary, optional prose, and H2 sections of links, each written as a Markdown link followed by a colon and a short note. A section named Optional marks links an agent can skip when its context window is tight. That is the whole format. Everything else is editorial judgment, and that is where most files fall short. #### The Suede file, section by section ##### The H1 and the blockquote Our H1 is "Suede Docs". The blockquote says what the docs cover and, in the same sentence, names the canonical source: the GitHub README at `github.com/Suede-AI/suede-docs`, which this site mirrors. An assistant that reads only two lines still learns where the authoritative copy lives. Put your canonical source in the first sentence an agent will read. ##### One scoping paragraph Below the blockquote sits a single paragraph stating that AI music is one implementation area for Suede, not the whole product. That line is there so an assistant does not describe Suede as only a music generator. If answer engines get your business slightly wrong, the correction belongs in this paragraph, written as a plain fact. ##### Link notes that carry the fact Here are two ways to describe the same page: ``` - [Create Music](https://docs.suedeai.ai/endpoints/create-music): Music endpoint docs. - [Create Music](https://docs.suedeai.ai/endpoints/create-music): POST /create-music, a full original song from a text prompt, $0.50 USDC on Base. ``` The second note answers "what does it cost" without a click. Jason Colapietro writes every note in our file to hold the method, the path and the number someone is most likely to ask about. A dental practice in Jupiter would put the service, the town and the booking route in the same spot. ##### A dated section header The API guides section opens with a dated line, "Checked against the live API on 2026-10-11", and then names where the prices come from. The date tells a reader how fresh the prices are, and it gives us a single line to update when we recheck. Undated numbers in an index file are how stale prices spread from one assistant answer to the next. ##### Optional, used on purpose Our Optional section holds the IP registry, the agency and the SEO practice. They are real pages, but they are not what a developer asking about endpoints needs. Filing them under Optional keeps the core list short without hiding anything. #### The guards that keep it current Short files drift quietly. On this site, `scripts/verify-site.mjs` fails when any guide or note is missing from llms.txt, when llms.txt stops pointing at [llms-full.txt](https://docs.suedeai.ai/llms-full.txt), when the full-text file grows past 500 KB, or when a banned unverifiable claim appears in either file. This note could not ship until its own entry was added to the index. Jason Colapietro's view is that an index nobody tests turns into a list of things that used to be true. #### How to tell whether anything reads it The plain answer first: llms.txt is a proposal, not a ranking signal any major search engine has announced. The file earns its keep through direct fetches. A developer pastes the URL into a coding assistant, an agent framework checks for it before crawling, or an answering tool fetches the root of a site it has already chosen to cite. Three checks tell you which of those is happening for you: 1. Search your server logs for requests to `/llms.txt` and `/llms-full.txt`, and record the user agents and the dates. 2. Paste the file URL into two or three assistants and ask a question only the file answers, such as a price or a service area. A wrong answer points at a weak note. 3. Run an AI readiness check. Suede Scan's explainer on [what an AI readiness score measures](https://optimize.suedeai.ai/notes/what-an-ai-readiness-score-measures) shows where llms.txt sits among the other signals. The pattern carries well beyond developer docs. Suede DNA's article on [structured data for a guitar rig archive](https://dna.suedeai.ai/articles/rig-archive-structured-data-for-ai-answers) shows a music archive where llms.txt, the sitemap and the robots tag all read one rule, so the three can never disagree about which pages count. #### The tradeoffs Notes that carry facts take longer to write and must change whenever a price or a page changes; a sitemap-style file never goes stale because it says nothing. Every date in the file creates recheck work. And llms.txt repeats facts your pages already state, so you need a test or a generator to keep the two in step. Suede accepts that cost because one stale price in an agent's answer is harder to correct than one extra line of maintenance. #### Credentials behind the method Jason Colapietro holds the Semrush Academy AI Search Operating System certificate and the Claude Academy badge Model Context Protocol: Advanced topics, among 21 earned course credentials across eight providers ([credential gallery](https://seo.suedeai.ai/evidence#training-credentials)). He is the author of five books on Amazon, including [Proof as Infrastructure](https://www.amazon.com/dp/B0GMB2VLXQ), and Suede AI is a member of Claude for Startups, Anthropic's startup program ([evidence](https://seo.suedeai.ai/evidence#claude-for-startups)). Suede AI ranks among [Clutch](https://clutch.co/profile/suede-ai-seo)'s [Top 30 AI Consultants in Florida](https://clutch.co/consulting/ai/florida) and [Top 50 AI Consultants nationwide](https://clutch.co/us/consulting/ai) (November 2026). In a separate listing, on October 31, 2026, Suede AI SEO ranked #1 among Palm Beach County-based companies in The Manifest's Florida AI Deployment directory and top 25 statewide ([The Manifest](https://themanifest.com/artificial-intelligence/consulting/deployment/companies/florida)). #### Your next step Open your own `/llms.txt`. If it does not exist, write the H1, a blockquote that names your canonical source, and five links whose notes each carry one fact. If it exists, rewrite the three weakest notes. Then book the free [Suede AI assessment](https://suedeai.agency/assessment), and our [AI visibility team](https://suedeai.agency/services/ai-visibility) in West Palm Beach will test how assistants answer from your file before and after the change. Suede AI, formerly Suede Labs, publishes this file and its guards in the open so you can copy the pattern. For the record behind the work, read [Jason Colapietro's founder profile](https://suedeai.ai/founder). #### More notes - [Writing developer docs that AI assistants quote correctly](https://docs.suedeai.ai/notes/ai-quotable-developer-docs): The source, date and verification rules behind docs.suedeai.ai, and how a Palm Beach County business can apply them. - [An API documentation checklist for agency-built integrations](https://docs.suedeai.ai/notes/api-docs-checklist-agency-integrations): Seven groups of checks for agencies in West Palm Beach and Jupiter that hand client integrations to the next developer. **Jason Colapietro**, founder of Suede AI, West Palm Beach, Florida. Read the [founder profile on suedeai.ai](https://suedeai.ai/founder) or visit [jasoncolapietro.com](https://jasoncolapietro.com/).