{"openapi":"3.1.0","info":{"title":"SoundCloud API (Bowmark)","version":"e833508f87ff","description":"SoundCloud (soundcloud.com) — live track search over SoundCloud's own catalogue, reading one track URL back to its full detail (artwork, description, genre, release date, label), and reading a set/playlist/album URL back to its tracks IN THE CURATOR'S ORDER. Returns the artist, public track URL, duration and play count. Direct JSON API, no browser.\n\nEvery function Bowmark has for SoundCloud (soundcloud.com) as one HTTP call. Each runs on Bowmark's infrastructure with the same billing, rules and response envelope as `POST /v1/run`. The whole API: https://api.bowmark.ai/openapi.json. Guide: https://bowmark.ai/docs/api.","contact":{"email":"support@bowmark.ai","url":"https://bowmark.ai/docs/api"}},"servers":[{"url":"https://api.bowmark.ai"}],"security":[{"bearer":[]},{"apiKeyHeader":[]}],"paths":{"/v1/sites/soundcloud/search":{"post":{"operationId":"search","summary":"Searches SoundCloud's catalogue for tracks matching a free-text query and returns up to `limit` rows (default 20, max 200) in SoundCloud's own relevance order.","description":"Searches SoundCloud's catalogue for tracks matching a free-text query and returns up to `limit` rows (default 20, max 200) in SoundCloud's own relevance order. Hits SoundCloud's JSON API directly — no browser, ~0.5s.\n\nCalls `bowmark.providers.soundcloud.search`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ScTrack[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"TypeScript: `string`"},"limit":{"type":"number","description":"TypeScript: `number`"}},"required":["query"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{"type":"array","items":{"$ref":"#/components/schemas/ScTrack"}}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/soundcloud/getTrack":{"post":{"operationId":"getTrack","summary":"Reads one soundcloud.com track URL — a `soundcloud.com/<account>/<track>` string, or a row `search` returned — and returns its full metadata: title, artist, duration, plays, likes, artwork, descriptio","description":"Reads one soundcloud.com track URL — a `soundcloud.com/<account>/<track>` string, or a row `search` returned — and returns its full metadata: title, artist, duration, plays, likes, artwork, description, genre, release date and label. Same JSON API, no browser, ~1-4s. THROWS rather than returning null when the URL resolves to an account or a set, or to nothing at all (deleted, private, or misspelled) — the caller asked about one specific track, so a wrong object would be worse than an error.\n\nCalls `bowmark.providers.soundcloud.getTrack`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ScTrackDetail>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"track":{"anyOf":[{"type":"string"},{"$ref":"#/components/schemas/ScTrack"}],"description":"TypeScript: `string | ScTrack`"}},"required":["track"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/soundcloud/getPlaylist":{"post":{"operationId":"getPlaylist","summary":"Reads a SoundCloud set URL — `soundcloud.com/<account>/sets/<name>`, a playlist, album, EP or compilation — and returns the set plus its tracks IN THE CURATOR'S ORDER, which is the whole reason to rea","description":"Reads a SoundCloud set URL — `soundcloud.com/<account>/sets/<name>`, a playlist, album, EP or compilation — and returns the set plus its tracks IN THE CURATOR'S ORDER, which is the whole reason to read a set rather than search. Up to `limit` tracks (default 200, max 500); compare `tracks.length` against `trackCount` to see a cap or a track that has since gone private. Same JSON API, no browser: the set arrives in one call with only its first 5 tracks filled in, and the rest are hydrated 50 at a time (~1s a batch), so a 27-track set is 2 calls and a 200-track set is 5. THROWS when the URL resolves to a track or an account, when the set is gone, or when the set lists tracks and none of them could be read — an empty track list would be a failed read wearing a success costume.\n\nCalls `bowmark.providers.soundcloud.getPlaylist`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ScPlaylist>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"playlist":{"anyOf":[{"type":"string"},{"$ref":"#/components/schemas/ScPlaylist"}],"description":"TypeScript: `string | ScPlaylist`"},"limit":{"type":"number","description":"TypeScript: `number`"}},"required":["playlist"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{"$ref":"#/components/schemas/ScPlaylist"}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your Bowmark API key."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Bowmark-Key"}},"responses":{"NotFound":{"description":"No such site or function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}},"schemas":{"RunEnvelope":{"type":"object","description":"What a run returns. `status` says whether the SCRIPT succeeded. A script that threw or paused for a login is still HTTP 200. Branch on `status`, not on the HTTP code.","required":["ok","status","result","logs","error","ms"],"properties":{"runId":{"type":"string","description":"Stable id for this run. Quote it in a support or `report` message."},"ok":{"type":"boolean","description":"False only when the run produced nothing usable."},"status":{"type":"string","enum":["ok","error","partial","needs_user"],"description":"`partial`: the result is real but some calls failed (see `incomplete`); `ok` stays true. `needs_user`: a person must sign in to a site first. Relay `meta.handoff.url` to them, then run again."},"egress":{"type":"string","enum":["default","link"],"description":"The egress the run was given, present only when the request asked for one. `link`: every request went through the caller's own Chrome (Bowmark Buddy)."},"result":{"description":"Whatever the script `return`ed. Any JSON value."},"logs":{"type":"array","items":{"type":"string"},"description":"Lines the script wrote with `log(...)`."},"error":{"type":["string","null"],"description":"Why the run failed, in plain words. Null on success."},"ms":{"type":"integer","description":"How long the script itself ran, in milliseconds."},"queuedMs":{"type":"integer","description":"How long the run waited for a worker before starting. Present only when it was a second or more."},"needs":{"type":"array","description":"The sign-ins this script is waiting on. Present when `status` is `needs_user`.","items":{"type":"object","required":["capability","provider","providerTitle","kind"],"properties":{"capability":{"type":"string"},"provider":{"type":"string"},"providerTitle":{"type":"string","description":"The site's name, to show a person."},"kind":{"type":"string"}}}},"incomplete":{"type":"object","description":"Present only when `status` is `partial`: which calls did not answer.","properties":{"summary":{"type":"string"},"totalCalls":{"type":"integer"}},"additionalProperties":true},"emptyHanded":{"type":"object","description":"Present when the script returned nothing while its calls returned rows, usually a filter that matched none of the site's own labels. Lists the label values the calls actually returned.","additionalProperties":true},"notes":{"type":"array","description":"Caveats a call attached to a complete answer. Never changes `status`.","items":{"type":"object","properties":{"path":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}}},"meta":{"type":"object","properties":{"handoff":{"type":"object","description":"A single-use sign-in link for a person to open. Expires at `expiresAt`.","properties":{"ref":{"type":"string"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}},"concurrency":{"type":"object","description":"On a 429: how many runs are in flight and when to retry.","properties":{"limit":{"type":"integer"},"inFlight":{"type":"integer"},"retryAfterSeconds":{"type":"integer"}}}},"additionalProperties":true},"notice":{"type":"object","description":"Set when the account owner has not accepted the current Terms. Relay it to them.","additionalProperties":true}}},"ScPlaylist":{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"url":{"type":"string"},"curator":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"artworkUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"genre":{"anyOf":[{"type":"string"},{"type":"null"}]},"isAlbum":{"type":"boolean"},"setType":{"anyOf":[{"type":"string"},{"type":"null"}]},"trackCount":{"type":"number"},"durationMs":{"type":"number"},"likeCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"tracks":{"type":"array","items":{"$ref":"#/components/schemas/ScTrack"}}},"required":["id","title","url","curator","description","artworkUrl","genre","isAlbum","setType","trackCount","durationMs","likeCount","createdAt","tracks"],"additionalProperties":true},"ScTrack":{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"artist":{"type":"string"},"url":{"type":"string"},"durationMs":{"type":"number"},"playCount":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","title","artist","url","durationMs","playCount"],"additionalProperties":true}}}}