{"__v":1,"_id":"57f553899757b12000145553","api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"body":"The Mixmax [REST API](https://cloud.google.com/apis/design/resources) allows you programmatic access to read and modify your data in Mixmax. It's available to all users. Note that some APIs are restricted to [Mixmax Professional](https://mixmax.com/pricing) and [Mixmax Premium](https://mixmax.com/pricing) users.\n\nPlease let us know how you're using the Mixmax API and what we can do to make it better. Email us at [hello:::at:::mixmax.com](mailto:hello@mixmax.com).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication\"\n}\n[/block]\nTo begin, create a developer token in your [Mixmax Settings](https://app.mixmax.com/dashboard/settings/integrations).\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/62589ca-Screen_Shot_2016-10-25_at_5.01.38_PM.png\",\n        \"Screen Shot 2016-10-25 at 5.01.38 PM.png\",\n        332,\n        179,\n        \"#2756a3\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\nKeep your token in a safe place, as it will only be given to you once and then stored securely. You can use your token to call the API by passing it as the value of the `apiToken` querystring parameter. or using the HTTP custom header `X-API-Token`. Here's an example of the latter using curl:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl --header \\\"X-API-Token: 45e99c6b-386d-4aa1-a2b4-296568a40ff2\\\" https://api.mixmax.com/v1/users/me\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nOr in the browser, using jQuery:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.ajax({\\n  url: 'https://api.mixmax.com/v1/users/me',\\n  headers: {\\n    'X-API-Token': '45e99c6b-386d-4aa1-a2b4-296568a40ff2'\\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nYou can also use your API token directly in this documentation. Underneath the API you want to use, click the green key next to Try It Out:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f6369ec-Screen_Shot_2016-10-26_at_12.19.01_PM.png\",\n        \"Screen Shot 2016-10-26 at 12.19.01 PM.png\",\n        450,\n        78,\n        \"#64ba64\"\n      ]\n    }\n  ]\n}\n[/block]\nand paste your token in, like this:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1c3b831-Screen_Shot_2016-10-26_at_12.19.14_PM.png\",\n        \"Screen Shot 2016-10-26 at 12.19.14 PM.png\",\n        451,\n        166,\n        \"#2b2b2b\"\n      ]\n    }\n  ]\n}\n[/block]\nThen you can use any API and see the live results.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Request content types\"\n}\n[/block]\nThe API accepts POST, PATCH, and PUT request bodies to be passed in the following content-type formats: `application/x-www-form-urlencoded` or `application/json`.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Pagination\"\n}\n[/block]\nAPI responses that return collections are always returned with the newest object first (by when they were created). When querying a collection through the API, the following querystrings are supported:\n\n* `limit` - *{Number}* A number between 1 and 25. The number of results you'd like to get back in each page. Defaults to 25.\n* `next` - *{String}* The string \"cursor\" to start fetching the next page of results (from a previous API response - see below).\n* `previous` - *{String}* The string \"cursor\" to start fetching the previous page of results if you're walking pages backwards (from a API response - see below).\n\nAll successful (HTTP status code: 200) responses for collections will have the following structure:\n\n* `results` *{Array}* An array of objects that are returned by the query.\n* `next` - *{String}* A cursor used to fetch the next page in the collection, for pagination. The next page can be fetched by passing `?next=<value>` on the querystring of the next request.\n* `hasNext` - *{Boolean}* Set to true if querying with `next` will return more results. If this is set to `false` you can still query the next page to pick up results that were added after the first query was run.\n* `previous` - *{String}* A cursor used to fetch the previous page of the collection, for pagination. The previous page can be fetched by passing `?previous=<value>` on the querystring of the next request.\n* `hasPrevious` - *{Boolean}* Set to true if querying with `previous` will return more results. If this is set to `false` you can still query the previous page to pick up results that were added after this query was originally run. Since most APIs are reverse-chronologically ordered, you can poll `?previous=<value>` to pick up new objects that are added to a collection.\n\n**Example:**\n\nAPI `polls?limit=10` returns the response:\n```\n{\n   results: [ ... ],\n   next: \"MTQ3NzQ0ODc1MTg4Mg\",\n   hasMore: true\n}\n```\n\nTo query the next page, pass the `next` parameter on the URL: https://api.mixmax.com/v1/polls?limit=10&next=MTQ3NzQ0ODc1MTg4Mg. The `next` and `previous` parameters are always URL safe strings so they don't need to be escaped.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Fields & expansions\"\n}\n[/block]\nBy default, all APIs return all properties of the response objects. For APIs that return collections, you can have it return only specific fields by passing a comma-delimited list of field names (using dot notation for nested properties) on the querystring as `fields`. For example: https://api.mixmax.com/v1/qa?fields=_id,title,users.userId will return just the `_id`, `title`, and the `userId` property on the nested `user` object.\n\nSome APIs support *expansions* that will return more detail about an existing property (usually a linked resource) OR a new meta-property (e.g. `count` of the number of subresources). They are documented in individual API documentation where they are supported (under *Query Params*). Expansions are requested by passing a comma-delimited list of field names on the querystring as `expand=`, e.g. https://api.mixmax.com/v1/sequences/1234?expand=stages,userId.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Rate limiting\"\n}\n[/block]\nAPI requests are limited to 120 requests per a 60 second window (per IP address and user). If you exceed your quota you will receive a HTTP `429` response with a `Retry-After` HTTP header.\n\nSome APIs have stricter rate limiting that is noted in the documentation for that API.\n\nEvery response from the API contains the following HTTP headers to let you know where you are at in your rate limiting: \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"HTTP Header\",\n    \"0-0\": \"X-RateLimit-Limit\",\n    \"1-0\": \"X-RateLimit-Reset\",\n    \"2-0\": \"X-RateLimit-Remaining\",\n    \"2-1\": \"Number of requests remaining for this time window\",\n    \"1-1\": \"Timestamp in UTC epoch seconds when rate limiting resets\",\n    \"0-1\": \"Total number of requests allowed in this time window\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nIf you'd like an increase in rate limiting, please contact us at support@mixmax.com.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Errors\"\n}\n[/block]\nThe Mixmax API uses standard HTTP responses codes to indicate errors. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted or document doesn't exist), and codes in the 5xx range indicate an error with Mixmax servers (these are rare). If there is a reason for the error, it will be returned in the JSON payload under the key `message`, e.g.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  message: \\\"Missing parameter teamIds\\\" \\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","category":"57f53fb368a53b2000e03f0f","createdAt":"2016-10-05T19:24:57.306Z","excerpt":"","githubsync":"","hidden":false,"isReference":true,"link_external":false,"link_url":"","next":{"description":"","pages":[]},"order":0,"parentDoc":null,"project":"5588b8a2f6c18d0d005bba03","slug":"getting-started-with-the-api","sync_unique":"","title":"Introduction: REST API","type":"basic","updates":[],"user":"5588b847f6c18d0d005bba01","version":"5588b8a2f6c18d0d005bba06","childrenPages":[]}

Introduction: REST API


The Mixmax [REST API](https://cloud.google.com/apis/design/resources) allows you programmatic access to read and modify your data in Mixmax. It's available to all users. Note that some APIs are restricted to [Mixmax Professional](https://mixmax.com/pricing) and [Mixmax Premium](https://mixmax.com/pricing) users. Please let us know how you're using the Mixmax API and what we can do to make it better. Email us at [hello@mixmax.com](mailto:hello@mixmax.com). [block:api-header] { "type": "basic", "title": "Authentication" } [/block] To begin, create a developer token in your [Mixmax Settings](https://app.mixmax.com/dashboard/settings/integrations). [block:image] { "images": [ { "image": [ "https://files.readme.io/62589ca-Screen_Shot_2016-10-25_at_5.01.38_PM.png", "Screen Shot 2016-10-25 at 5.01.38 PM.png", 332, 179, "#2756a3" ], "border": true } ] } [/block] Keep your token in a safe place, as it will only be given to you once and then stored securely. You can use your token to call the API by passing it as the value of the `apiToken` querystring parameter. or using the HTTP custom header `X-API-Token`. Here's an example of the latter using curl: [block:code] { "codes": [ { "code": "curl --header \"X-API-Token: 45e99c6b-386d-4aa1-a2b4-296568a40ff2\" https://api.mixmax.com/v1/users/me", "language": "curl" } ] } [/block] Or in the browser, using jQuery: [block:code] { "codes": [ { "code": "$.ajax({\n url: 'https://api.mixmax.com/v1/users/me',\n headers: {\n 'X-API-Token': '45e99c6b-386d-4aa1-a2b4-296568a40ff2'\n }\n});", "language": "javascript" } ] } [/block] You can also use your API token directly in this documentation. Underneath the API you want to use, click the green key next to Try It Out: [block:image] { "images": [ { "image": [ "https://files.readme.io/f6369ec-Screen_Shot_2016-10-26_at_12.19.01_PM.png", "Screen Shot 2016-10-26 at 12.19.01 PM.png", 450, 78, "#64ba64" ] } ] } [/block] and paste your token in, like this: [block:image] { "images": [ { "image": [ "https://files.readme.io/1c3b831-Screen_Shot_2016-10-26_at_12.19.14_PM.png", "Screen Shot 2016-10-26 at 12.19.14 PM.png", 451, 166, "#2b2b2b" ] } ] } [/block] Then you can use any API and see the live results. [block:api-header] { "type": "basic", "title": "Request content types" } [/block] The API accepts POST, PATCH, and PUT request bodies to be passed in the following content-type formats: `application/x-www-form-urlencoded` or `application/json`. [block:api-header] { "type": "basic", "title": "Pagination" } [/block] API responses that return collections are always returned with the newest object first (by when they were created). When querying a collection through the API, the following querystrings are supported: * `limit` - *{Number}* A number between 1 and 25. The number of results you'd like to get back in each page. Defaults to 25. * `next` - *{String}* The string "cursor" to start fetching the next page of results (from a previous API response - see below). * `previous` - *{String}* The string "cursor" to start fetching the previous page of results if you're walking pages backwards (from a API response - see below). All successful (HTTP status code: 200) responses for collections will have the following structure: * `results` *{Array}* An array of objects that are returned by the query. * `next` - *{String}* A cursor used to fetch the next page in the collection, for pagination. The next page can be fetched by passing `?next=<value>` on the querystring of the next request. * `hasNext` - *{Boolean}* Set to true if querying with `next` will return more results. If this is set to `false` you can still query the next page to pick up results that were added after the first query was run. * `previous` - *{String}* A cursor used to fetch the previous page of the collection, for pagination. The previous page can be fetched by passing `?previous=<value>` on the querystring of the next request. * `hasPrevious` - *{Boolean}* Set to true if querying with `previous` will return more results. If this is set to `false` you can still query the previous page to pick up results that were added after this query was originally run. Since most APIs are reverse-chronologically ordered, you can poll `?previous=<value>` to pick up new objects that are added to a collection. **Example:** API `polls?limit=10` returns the response: ``` { results: [ ... ], next: "MTQ3NzQ0ODc1MTg4Mg", hasMore: true } ``` To query the next page, pass the `next` parameter on the URL: https://api.mixmax.com/v1/polls?limit=10&next=MTQ3NzQ0ODc1MTg4Mg. The `next` and `previous` parameters are always URL safe strings so they don't need to be escaped. [block:api-header] { "type": "basic", "title": "Fields & expansions" } [/block] By default, all APIs return all properties of the response objects. For APIs that return collections, you can have it return only specific fields by passing a comma-delimited list of field names (using dot notation for nested properties) on the querystring as `fields`. For example: https://api.mixmax.com/v1/qa?fields=_id,title,users.userId will return just the `_id`, `title`, and the `userId` property on the nested `user` object. Some APIs support *expansions* that will return more detail about an existing property (usually a linked resource) OR a new meta-property (e.g. `count` of the number of subresources). They are documented in individual API documentation where they are supported (under *Query Params*). Expansions are requested by passing a comma-delimited list of field names on the querystring as `expand=`, e.g. https://api.mixmax.com/v1/sequences/1234?expand=stages,userId. [block:api-header] { "type": "basic", "title": "Rate limiting" } [/block] API requests are limited to 120 requests per a 60 second window (per IP address and user). If you exceed your quota you will receive a HTTP `429` response with a `Retry-After` HTTP header. Some APIs have stricter rate limiting that is noted in the documentation for that API. Every response from the API contains the following HTTP headers to let you know where you are at in your rate limiting: [block:parameters] { "data": { "h-0": "HTTP Header", "0-0": "X-RateLimit-Limit", "1-0": "X-RateLimit-Reset", "2-0": "X-RateLimit-Remaining", "2-1": "Number of requests remaining for this time window", "1-1": "Timestamp in UTC epoch seconds when rate limiting resets", "0-1": "Total number of requests allowed in this time window" }, "cols": 2, "rows": 3 } [/block] If you'd like an increase in rate limiting, please contact us at support@mixmax.com. [block:api-header] { "type": "basic", "title": "Errors" } [/block] The Mixmax API uses standard HTTP responses codes to indicate errors. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted or document doesn't exist), and codes in the 5xx range indicate an error with Mixmax servers (these are rare). If there is a reason for the error, it will be returned in the JSON payload under the key `message`, e.g. [block:code] { "codes": [ { "code": "{\n message: \"Missing parameter teamIds\" \n}", "language": "json" } ] } [/block]