Marketo REST APIOpenAPI 3 Definition
An unofficial, single-file OpenAPI 3.0.3 definition covering the whole public Adobe Marketo Engage REST API: Identity, Lead Database & Marketing Activities, Asset, and User Management — merged, converted, and validated as one document.
Four Swagger 2.0 documents, one OpenAPI 3 spec
Adobe publishes these four surfaces as four separate Swagger 2.0 documents on developer.adobe.com/marketo-apis. That split is awkward in practice — most tooling (client generators, mock servers, API gateways, LLM tool definitions) wants one OpenAPI 3 document with one server, one security scheme, and one set of shared schemas. This is that document.
The merge is clean: no path collides across the four specs, all 360 operationIds are unique, and the build fails loudly on any collision it doesn't already know how to resolve — so an upstream change can't silently drop an endpoint. Three genuine upstream defects are corrected as named patches, and the tag descriptions have been rewritten from Springfox artifacts (“Email Controller”) into documentation that says what each tag actually covers.
360 operations across 308 paths
/identityOAuth 2.0 token issuance.
/rest/v1, /bulk/v1People, activities, campaigns, program members, static lists, custom objects, companies, opportunities, sales persons, named accounts, API usage, bulk import/export.
/rest/asset/v1Emails and templates (classic and new Email Designer), fragments, landing pages, redirect rules, forms, programs, smart campaigns, smart lists, snippets, segments, folders, files, tags, channels, tokens.
/rest/v1/userManagementUsers, roles, workspaces, invitations.
Endpoint, credentials, token, call
Find your endpoint
In Marketo, go to Admin → Web Services. The 123-ABC-456 part of your REST endpoint is your Munchkin ID. The spec declares a single server with a munchkinId variable, so set it once and every path resolves.
https://{munchkinId}.mktorest.comGet credentials
Admin → Integration → LaunchPoint → New Service, service type Custom. Assign an API-only user whose role has the permissions you need — every operation's description names them, e.g. Required Permissions: Read-Write Lead. You get a Client ID and Client Secret.
Get a token
Tokens last one hour. Cache and reuse them — reissuing on every call is the single most common cause of hitting the rate limit. Calls to this endpoint don't count against your daily quota.
curl -s "https://123-ABC-456.mktorest.com\
/identity/oauth/token\
?grant_type=client_credentials\
&client_id=$CLIENT_ID\
&client_secret=$CLIENT_SECRET"Things the spec can't tell you
These behaviours are documented in the spec's info.description, but they're worth stating plainly because they trip up nearly every new Marketo integration.
Errors come back as HTTP 200
Marketo answers almost every request with 200 OK and reports failure in the body. Branch on success, not on the status code. Worth handling specifically: 602 (token expired — refresh and retry), 601 (token invalid), 603 (access denied), 606 (rate limit), 607 (daily quota, resets 12:00 AM CST), and the record-level 1003/1004/1006/1013. A batch call can return success: true with per-record failures inside result[].
Two different paging schemes
Lead Database (/rest/v1, /bulk/v1) pages with tokens — when moreResult is true, pass nextPageToken on the next call, batch size caps at 300. Asset (/rest/asset/v1) pages with offset and maxReturn, max 200, default 20.
Rate limits
100 calls per 20 seconds, 10 concurrent calls, and a daily quota of 50,000 by default. The Usage tag has endpoints for daily call and error counts by user and day. Bulk Export carries its own separate quota — 500 MB of uncompressed data per day.
Asset endpoints take form-encoded bodies
Most Asset write operations consume application/x-www-form-urlencoded, not JSON — the spec records this per operation in requestBody.content. Lead Database writes use application/json; bulk imports and file uploads use multipart/form-data. Getting this wrong produces confusing "missing required field" errors.
Browse the spec
Read-only. Every operation, parameter, schema, and response is here to browse and deep-link, but nothing sends a request — no credentials are ever entered on this page. To actually call the API, import the Postman collection, which is generated from this same spec.
Want to send the calls, not just read them?
The Postman collection is generated from this same spec — all 360 endpoints in 43 folders, with OAuth token handling wired in and tests that catch Marketo's HTTP 200 errors.
Source, license, and the official docs
The spec, the build script, and its documentation are MIT licensed. Your use of the Marketo Engage API itself is governed by Adobe's API License Agreement, not by this one.
jdarring/marketo-openapi