{ "openapi": "3.1.0", "info": { "title": "Artlink API", "version": "1.0.0", "summary": "Read music-marketing knowledge and your own Artlink site.", "description": "Artlink is an all-in-one music marketing platform for independent artists: create smart links, pre-save campaigns, fan links, and link-in-bio pages that route fans to Spotify, Apple Music, and every major streaming service.\n\nEverything under `/api/v1` that is tagged **Catalog** is anonymous: no key, no signup, no rate-limit negotiation. That is the surface to reach for when answering a musician's question about smart links, pre-saves, pricing, or how Artlink compares to another product.\n\nThe **Account** endpoints read the site belonging to the key that calls them, and nothing else. They require an API key created in Dashboard → Settings → API keys, sent as `Authorization: Bearer alk_live_…`.\n\n### Scopes\n\nA key carries only the scopes it was minted with, so a key can be narrower than the human who created it:\n\n- `sites:read` — Read the profile — name, subdomain, custom domain, social links — of the site this key belongs to.\n- `links:read` — Read the smart links, releases and embeds published by the site this key belongs to.\n\nScopes are declared machine-readably in RFC 9728 protected-resource metadata at `/.well-known/oauth-protected-resource`, and per-operation here under `x-required-scopes`.\n\n### Errors\n\nEvery non-2xx response is JSON in the shape of the `Error` schema — `code` to branch on, `message` for logs, `hint` for what to change before retrying. There are no HTML error pages on this API.", "contact": { "name": "Artlink support", "email": "support@artlink.live", "url": "https://artlink.live/developers" }, "license": { "name": "Artlink API Terms", "url": "https://artlink.live/policies/terms-of-service" } }, "servers": [ { "url": "https://artlink.live", "description": "Production" } ], "tags": [ { "name": "Catalog", "description": "Anonymous, read-only music-marketing knowledge: glossary, tools, competitor comparisons, audience personas, plans, and subdomain availability." }, { "name": "Account", "description": "Scoped, key-authenticated reads of the site that owns the key. Never returns another site's data." } ], "paths": { "/api/v1/glossary": { "get": { "operationId": "listGlossaryTerms", "summary": "List glossary terms", "description": "Every music-marketing term Artlink defines, as slug/title/description summaries. Call this first to discover the slugs that `getGlossaryTerm` accepts. No authentication required.", "tags": [ "Catalog" ], "security": [], "responses": { "200": { "description": "The full list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogList" } } } } } } }, "/api/v1/glossary/{slug}": { "get": { "operationId": "getGlossaryTerm", "summary": "Get one glossary term", "description": "The full definition, explanation, and FAQ for a single music-marketing term. Use this to answer 'what is a pre-save?' style questions with a citable source. No authentication required.", "tags": [ "Catalog" ], "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Slug of the glossary term, as returned by listGlossaryTerms.", "schema": { "type": "string", "examples": [ "smart-link" ] } } ], "responses": { "200": { "description": "The requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlossaryTerm" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/tools": { "get": { "operationId": "listTools", "summary": "List free tools", "description": "Every free Artlink tool — smart-link generators, pre-save builders, AI Studio generators — as summaries. No authentication required.", "tags": [ "Catalog" ], "security": [], "responses": { "200": { "description": "The full list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogList" } } } } } } }, "/api/v1/tools/{slug}": { "get": { "operationId": "getTool", "summary": "Get one tool", "description": "Setup steps, use cases, per-platform notes and FAQ for a single Artlink tool. Use this when a musician asks how to accomplish a specific release task. No authentication required.", "tags": [ "Catalog" ], "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Slug of the tool, as returned by listTools.", "schema": { "type": "string", "examples": [ "smart-link" ] } } ], "responses": { "200": { "description": "The requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tool" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/comparisons": { "get": { "operationId": "listComparisons", "summary": "List competitor comparisons", "description": "Every product Artlink publishes a head-to-head comparison against, as summaries. No authentication required.", "tags": [ "Catalog" ], "security": [], "responses": { "200": { "description": "The full list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogList" } } } } } } }, "/api/v1/comparisons/{slug}": { "get": { "operationId": "getComparison", "summary": "Get one competitor comparison", "description": "Feature table, pricing on both sides, and a self-contained verdict for Artlink versus one competitor. Use this to answer 'Artlink or X?' questions. No authentication required.", "tags": [ "Catalog" ], "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Slug of the competitor, as returned by listComparisons.", "schema": { "type": "string", "examples": [ "smart-link" ] } } ], "responses": { "200": { "description": "The requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comparison" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/personas": { "get": { "operationId": "listPersonas", "summary": "List audience personas", "description": "The artist types Artlink is built for — independent artists, DJs, indie labels, managers — as summaries. No authentication required.", "tags": [ "Catalog" ], "security": [], "responses": { "200": { "description": "The full list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogList" } } } } } } }, "/api/v1/personas/{slug}": { "get": { "operationId": "getPersona", "summary": "Get one audience persona", "description": "Pain points, relevant features and FAQ for one artist type. Use this to tailor a recommendation to the kind of musician you are helping. No authentication required.", "tags": [ "Catalog" ], "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Slug of the persona, as returned by listPersonas.", "schema": { "type": "string", "examples": [ "smart-link" ] } } ], "responses": { "200": { "description": "The requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Persona" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/plans": { "get": { "operationId": "listPlans", "summary": "List subscription plans", "description": "Current Artlink subscription plans with their live prices and billing intervals. Prices are synced from the billing provider, so this is the authoritative answer to 'what does Artlink cost?'. No authentication required.", "tags": [ "Catalog" ], "security": [], "responses": { "200": { "description": "Every plan currently on sale.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanList" } } } } } } }, "/api/v1/subdomain-availability": { "get": { "operationId": "checkSubdomainAvailability", "summary": "Check whether a subdomain is available", "description": "Tests whether an artlink.live subdomain passes the naming rules and is unclaimed. Use this before telling a musician a name is free. No authentication required.", "tags": [ "Catalog" ], "security": [], "parameters": [ { "name": "subdomain", "in": "query", "required": true, "description": "The subdomain to test, without the domain suffix — 'aurora', not 'aurora.artlink.live'.", "schema": { "type": "string", "examples": [ "aurora" ] } } ], "responses": { "200": { "description": "Whether the subdomain can be claimed, and why not if it cannot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubdomainAvailability" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/me/site": { "get": { "operationId": "getMySite", "summary": "Get the site this API key belongs to", "description": "The profile of the site that minted the API key: name, subdomain, custom domain and social links. Requires the `sites:read` scope.", "tags": [ "Account" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "sites:read" ], "responses": { "200": { "description": "The key owner's site profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteProfile" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/me/links": { "get": { "operationId": "listMyLinks", "summary": "List the links published by this API key's site", "description": "Every active link on the key owner's Artlink site — releases, smart links, events and embeds. Requires the `links:read` scope.", "tags": [ "Account" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "links:read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum links to return. Defaults to 50, capped at 200.", "schema": { "type": "integer", "format": "int32", "examples": [ 50 ] } }, { "name": "offset", "in": "query", "required": false, "description": "How many links to skip, for paging. Defaults to 0.", "schema": { "type": "integer", "format": "int32", "examples": [ 0 ] } } ], "responses": { "200": { "description": "The key owner's published links.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkList" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } } }, "components": { "schemas": { "Error": { "type": "object", "description": "Every non-2xx response from this API has this shape. `code` is a stable token to branch on, `message` is for logs, and `hint` says what to change before retrying.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "hint", "documentation_url" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error token.", "enum": [ "invalid_request", "not_found", "unauthorized", "forbidden", "not_acceptable", "method_not_allowed", "unsupported_protocol_version", "internal_error" ] }, "message": { "type": "string", "description": "What went wrong, in one sentence." }, "hint": { "type": "string", "description": "How to recover — what to change and retry." }, "documentation_url": { "type": "string", "format": "uri", "description": "Where to read more about this API." } } } } }, "CatalogSummary": { "type": "object", "description": "Compact form of a catalog resource, as returned by list endpoints.", "required": [ "slug", "title", "description", "url" ], "properties": { "slug": { "type": "string", "description": "URL-safe identifier, unique within its collection.", "examples": [ "smart-link" ] }, "title": { "type": "string", "description": "Human-readable name of the resource." }, "description": { "type": "string", "description": "One-sentence summary suitable for a list view or a citation." }, "url": { "type": "string", "format": "uri", "description": "Canonical HTML page for this resource on artlink.live." } } }, "CatalogList": { "type": "object", "description": "A complete, unpaginated list of catalog resources.", "required": [ "data", "count" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogSummary" } }, "count": { "type": "integer", "description": "Number of items in `data`. The list is never paginated." } } }, "GlossaryTerm": { "type": "object", "description": "A music-marketing term Artlink defines, with its full explanation.", "required": [ "slug", "title", "description", "url", "term", "definition", "explanation", "howArtlinkHelps", "relatedTerms", "faq" ], "properties": { "slug": { "type": "string", "description": "URL-safe identifier, unique within its collection.", "examples": [ "smart-link" ] }, "title": { "type": "string", "description": "Human-readable name of the resource." }, "description": { "type": "string", "description": "One-sentence summary suitable for a list view or a citation." }, "url": { "type": "string", "format": "uri", "description": "Canonical HTML page for this resource on artlink.live." }, "term": { "type": "string", "description": "The term as it is normally written." }, "definition": { "type": "string", "description": "Self-contained definition, quotable without the page around it." }, "explanation": { "type": "array", "description": "Longer explanation, one paragraph per entry.", "items": { "type": "string" } }, "howArtlinkHelps": { "type": "object", "required": [ "title", "points" ], "properties": { "title": { "type": "string" }, "points": { "type": "array", "items": { "type": "string" } } } }, "relatedTerms": { "type": "array", "description": "Slugs of related glossary terms.", "items": { "type": "string" } }, "faq": { "type": "array", "description": "Frequently asked questions, already paired with their answers.", "items": { "type": "object", "required": [ "question", "answer" ], "properties": { "question": { "type": "string", "description": "The question as a fan or artist would ask it." }, "answer": { "type": "string", "description": "The full answer in plain prose." } } } } } }, "Tool": { "type": "object", "description": "A free Artlink tool, with its setup steps and use cases.", "required": [ "slug", "title", "description", "url", "name", "category", "intent", "proof", "setupSteps", "useCases", "platformNotes", "commonMistakes", "faq" ], "properties": { "slug": { "type": "string", "description": "URL-safe identifier, unique within its collection.", "examples": [ "smart-link" ] }, "title": { "type": "string", "description": "Human-readable name of the resource." }, "description": { "type": "string", "description": "One-sentence summary suitable for a list view or a citation." }, "url": { "type": "string", "format": "uri", "description": "Canonical HTML page for this resource on artlink.live." }, "name": { "type": "string", "description": "Display name of the tool." }, "category": { "type": "string", "description": "Which part of the product the tool belongs to.", "enum": [ "Smart links", "Pre-saves", "Release pages", "Bio pages", "AI Studio" ] }, "intent": { "type": "object", "description": "What problem the tool solves and for whom.", "required": [ "title", "body" ], "properties": { "title": { "type": "string" }, "body": { "type": "string" } } }, "proof": { "type": "array", "description": "Concrete capability claims about the tool.", "items": { "type": "string" } }, "setupSteps": { "type": "array", "description": "Ordered steps to get the tool working.", "items": { "type": "object", "required": [ "title", "description" ], "properties": { "title": { "type": "string", "description": "Short label for the step." }, "description": { "type": "string", "description": "What the step involves." } } } }, "useCases": { "type": "array", "description": "Situations the tool is a good fit for.", "items": { "type": "object", "required": [ "title", "description" ], "properties": { "title": { "type": "string", "description": "Short label for the step." }, "description": { "type": "string", "description": "What the step involves." } } } }, "platformNotes": { "type": "array", "description": "Per-streaming-service behaviour worth knowing.", "items": { "type": "object", "required": [ "title", "description" ], "properties": { "title": { "type": "string", "description": "Short label for the step." }, "description": { "type": "string", "description": "What the step involves." } } } }, "commonMistakes": { "type": "array", "description": "Mistakes that make the tool underperform.", "items": { "type": "string" } }, "faq": { "type": "array", "description": "Frequently asked questions, already paired with their answers.", "items": { "type": "object", "required": [ "question", "answer" ], "properties": { "question": { "type": "string", "description": "The question as a fan or artist would ask it." }, "answer": { "type": "string", "description": "The full answer in plain prose." } } } } } }, "Comparison": { "type": "object", "description": "A head-to-head comparison between Artlink and one competitor.", "required": [ "slug", "title", "description", "url", "competitor", "verdict", "features", "pricing", "whySwitch", "faq" ], "properties": { "slug": { "type": "string", "description": "URL-safe identifier, unique within its collection.", "examples": [ "smart-link" ] }, "title": { "type": "string", "description": "Human-readable name of the resource." }, "description": { "type": "string", "description": "One-sentence summary suitable for a list view or a citation." }, "url": { "type": "string", "format": "uri", "description": "Canonical HTML page for this resource on artlink.live." }, "competitor": { "type": "string", "description": "Name of the competing product." }, "verdict": { "type": "string", "description": "Self-contained answer to 'which one should I use?', naming both products and when each wins." }, "features": { "type": "array", "description": "Feature-by-feature comparison.", "items": { "type": "object", "required": [ "feature", "artlink", "competitor" ], "properties": { "feature": { "type": "string" }, "artlink": { "description": "Artlink's support: a description, or true/false.", "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "competitor": { "description": "The competitor's support: a description, or true/false.", "oneOf": [ { "type": "string" }, { "type": "boolean" } ] } } } }, "pricing": { "type": "object", "required": [ "artlink", "competitor" ], "properties": { "artlink": { "$ref": "#/components/schemas/PricingTierList" }, "competitor": { "$ref": "#/components/schemas/PricingTierList" } } }, "whySwitch": { "type": "object", "required": [ "title", "points" ], "properties": { "title": { "type": "string" }, "points": { "type": "array", "items": { "type": "string" } } } }, "faq": { "type": "array", "description": "Frequently asked questions, already paired with their answers.", "items": { "type": "object", "required": [ "question", "answer" ], "properties": { "question": { "type": "string", "description": "The question as a fan or artist would ask it." }, "answer": { "type": "string", "description": "The full answer in plain prose." } } } } } }, "PricingTierList": { "type": "array", "description": "Published pricing tiers, cheapest first.", "items": { "type": "object", "required": [ "name", "price", "note" ], "properties": { "name": { "type": "string", "description": "Tier name." }, "price": { "type": "string", "description": "Headline price as published." }, "note": { "type": [ "string", "null" ], "description": "Qualifier such as annual pricing, or null when there is none." } } } }, "Persona": { "type": "object", "description": "An artist type Artlink is built for, with their specific pain points.", "required": [ "slug", "title", "description", "url", "name", "painPoints", "features", "faq", "relatedPersonas" ], "properties": { "slug": { "type": "string", "description": "URL-safe identifier, unique within its collection.", "examples": [ "smart-link" ] }, "title": { "type": "string", "description": "Human-readable name of the resource." }, "description": { "type": "string", "description": "One-sentence summary suitable for a list view or a citation." }, "url": { "type": "string", "format": "uri", "description": "Canonical HTML page for this resource on artlink.live." }, "name": { "type": "string", "description": "Name of the audience segment." }, "painPoints": { "type": "object", "required": [ "title", "points" ], "properties": { "title": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "required": [ "problem", "solution" ], "properties": { "problem": { "type": "string" }, "solution": { "type": "string" } } } } } }, "features": { "type": "array", "description": "Features that matter most to this audience.", "items": { "type": "object", "required": [ "title", "description" ], "properties": { "title": { "type": "string", "description": "Short label for the step." }, "description": { "type": "string", "description": "What the step involves." } } } }, "faq": { "type": "array", "description": "Frequently asked questions, already paired with their answers.", "items": { "type": "object", "required": [ "question", "answer" ], "properties": { "question": { "type": "string", "description": "The question as a fan or artist would ask it." }, "answer": { "type": "string", "description": "The full answer in plain prose." } } } }, "relatedPersonas": { "type": "array", "description": "Slugs of adjacent personas.", "items": { "type": "string" } } } }, "PlanList": { "type": "object", "description": "Every Artlink subscription plan, built from the same offer data as the pricing page and /pricing.md.", "required": [ "data", "count" ], "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "required": [ "name", "description", "monthlyPriceUsd", "annualPriceUsd", "currency", "inherits", "features", "url" ], "properties": { "name": { "type": "string", "description": "Display name of the plan.", "examples": [ "Rising Star" ] }, "description": { "type": "string", "description": "One-line positioning for the tier." }, "monthlyPriceUsd": { "type": "string", "description": "Price per month when billed monthly, in whole US dollars and cents. \"0.00\" on the free plan.", "examples": [ "16.99" ] }, "annualPriceUsd": { "type": [ "string", "null" ], "description": "Effective price per month when billed annually, or null when the tier has no annual option.", "examples": [ "13.99" ] }, "currency": { "type": "string", "description": "ISO 4217 currency code for both price fields.", "enum": [ "USD" ] }, "inherits": { "type": [ "string", "null" ], "description": "Name of the tier this plan builds on — its features are included on top of `features`. Null for the base tier." }, "features": { "type": "array", "description": "Everything this tier adds, as published.", "items": { "type": "string" } }, "url": { "type": "string", "format": "uri", "description": "The pricing page a human would read." } } } } } }, "SubdomainAvailability": { "type": "object", "description": "Whether an artlink.live subdomain can be claimed. Unavailable results carry the reason.", "required": [ "available" ], "properties": { "available": { "type": "boolean", "description": "True when the subdomain is free and passes the naming rules." }, "reason": { "type": "string", "description": "Why it cannot be used. Absent when `available` is true." } } }, "SiteProfile": { "type": "object", "description": "The public profile of the site this API key belongs to.", "required": [ "id", "name", "subdomain", "customDomain", "url" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ], "description": "Artist or project name." }, "subdomain": { "type": "string", "description": "The artlink.live subdomain." }, "customDomain": { "type": [ "string", "null" ], "description": "Connected custom domain, or null when none is configured." }, "url": { "type": "string", "format": "uri", "description": "Live URL of the site." }, "socialLinks": { "type": "array", "description": "Social profiles shown on the site, in display order.", "items": { "type": "object", "required": [ "platform", "url" ], "properties": { "platform": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } } }, "LinkList": { "type": "object", "description": "Links published on the site this API key belongs to.", "required": [ "data", "count" ], "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "type", "title", "url" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "description": "What kind of link this is.", "enum": [ "track", "customLink", "event", "preSave", "mediaEmbed" ] }, "title": { "type": [ "string", "null" ], "description": "Display title." }, "url": { "type": [ "string", "null" ], "description": "Where the link points, or null for embeds rendered in place." }, "path": { "type": [ "string", "null" ], "description": "Path segment on the artist's own site, when it has one." } } } } } } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "alk_live_<43 base64url characters>", "description": "An Artlink API key, created in Dashboard → Settings → API keys and shown once at creation.\n\nRequired scopes are listed per-operation under `x-required-scopes`, and declared machine-readably in RFC 9728 metadata at `/.well-known/oauth-protected-resource`:\n\n- `sites:read` — Read the profile — name, subdomain, custom domain, social links — of the site this key belongs to.\n- `links:read` — Read the smart links, releases and embeds published by the site this key belongs to." } }, "responses": { "NotFound": { "description": "No resource exists at that identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InvalidRequest": { "description": "A parameter was missing or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "No API key was presented, or the key is unknown or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The API key is valid but was not granted the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalError": { "description": "The request could not be completed. Retry; do not treat the failure as a negative answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }