docs/medium-api-v1-swagger.json
{
"swagger": "2.0",
"info": {
"title": "Medium API",
"description": "Articles that matter on social publishing platform",
"version": "1.0.0"
},
"host": "api.medium.com",
"schemes": [
"https"
],
"basePath": "/v1",
"produces": [
"application/json"
],
"paths": {
"/me": {
"get": {
"summary": "User Profile",
"description": "Getting the authenticated user’s details",
"produces": [
"application/json"
],
"tags": [
"User"
],
"responses": {
"200": {
"description": "a User object within a data envelope.",
"schema": {
"properties": {
"data": {
"description": "a user object within a data envelope",
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for the user."
},
"username": {
"type": "string",
"description": "The user’s username on Medium."
},
"name": {
"type": "string",
"description": "The user’s name on Medium."
},
"url": {
"type": "string",
"description": "The URL to the user’s profile on Medium."
},
"imageUrl": {
"type": "string",
"description": "The URL to the user’s avatar on Medium."
}
}
}
}
},
"examples": {
"application/json": "{\n \"data\": {\n \"id\": \"5303d74c64f66366f00cb9b2a94f3251bf5\",\n \"username\": \"majelbstoat\",\n \"name\": \"Jamie Talbot\",\n \"url\": \"https://medium.com/@majelbstoat\",\n \"imageUrl\": \"https://images.medium.com/0*fkfQiTzT7TlUGGyI.png\"\n }\n}"
}
},
"401": {
"description": "The \"accessToken\" is invalid or has been revoked."
}
}
}
},
"/users/{userId}/publications": {
"get": {
"summary": "User Publications",
"description": "Listing the user’s publications",
"parameters": [
{
"name": "userId",
"in": "path",
"description": "The id of the user being queried",
"required": true,
"type": "string"
}
],
"tags": [
"Publications"
],
"responses": {
"200": {
"description": "a list of publication objects",
"schema": {
"properties": {
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for the publication."
},
"name": {
"type": "string",
"description": "The publication’s name on Medium."
},
"description": {
"type": "string",
"description": "Short description of the publication"
},
"url": {
"type": "string",
"description": "The URL to the publication’s homepage"
},
"imageUrl": {
"type": "string",
"description": "The URL to the publication’s image/logo"
}
}
},
"description": "a list of publication objects within a data envelope"
}
}
},
"examples": {
"application/json": "{\n \"data\": [\n {\n \"id\": \"b969ac62a46b\",\n \"name\": \"About Medium\",\n \"description\": \"What is this thing and how does it work?\",\n \"url\": \"https://medium.com/about\",\n \"imageUrl\": \"https://cdn-images-1.medium.com/fit/c/200/200/0*ae1jbP_od0W6EulE.jpeg\"\n },\n {\n \"id\": \"b45573563f5a\",\n \"name\": \"Developers\",\n \"description\": \"Medium’s Developer resources\",\n \"url\": \"https://medium.com/developers\",\n \"imageUrl\": \"https://cdn-images-1.medium.com/fit/c/200/200/1*ccokMT4VXmDDO1EoQQHkzg@2x.png\"\n }\n ]\n}"
}
},
"401": {
"description": "Unauthorized: The accessToken is invalid, lacks the listPublications scope or has been revoked."
},
"403": {
"description": "Forbidden: The request attempts to list publications for another user."
}
}
}
},
"/publications/{publicationId}/contributors": {
"get": {
"summary": "Publication Contributors",
"description": "Fetching contributors for a publication",
"parameters": [
{
"name": "publicationId",
"in": "path",
"description": "The id of the publication being queried",
"required": true,
"type": "string"
}
],
"tags": [
"Publications"
],
"responses": {
"200": {
"description": "the contributors as list of resources under a publication",
"schema": {
"properties": {
"data": {
"type": "array",
"items": {
"properties": {
"publicationId": {
"type": "string",
"description": "An ID for the publication. This can be lifted from response of publications above"
},
"userId": {
"type": "string",
"description": "A user ID of the contributor."
},
"role": {
"type": "string",
"description": "Role of the user identified by userId in the publication identified by publicationId. 'editor' or 'writer'"
}
}
},
"description": "a list of contributor objects within a data envelope"
}
}
},
"examples": {
"application/json": "{\n \"data\": [\n {\n \"publicationId\": \"b45573563f5a\",\n \"userId\": \"13a06af8f81849c64dafbce822cbafbfab7ed7cecf82135bca946807ea351290d\",\n \"role\": \"editor\"\n },\n {\n \"publicationId\": \"b45573563f5a\",\n \"userId\": \"1c9c63b15b874d3e354340b7d7458d55e1dda0f6470074df1cc99608a372866ac\",\n \"role\": \"editor\"\n },\n {\n \"publicationId\": \"b45573563f5a\",\n \"userId\": \"1cc07499453463518b77d31650c0b53609dc973ad8ebd33690c7be9236e9384ad\",\n \"role\": \"editor\"\n },\n {\n \"publicationId\": \"b45573563f5a\",\n \"userId\": \"196f70942410555f4b3030debc4f199a0d5a0309a7b9df96c57b8ec6e4b5f11d7\",\n \"role\": \"writer\"\n },\n {\n \"publicationId\": \"b45573563f5a\",\n \"userId\": \"14d4a581f21ff537d245461b8ff2ae9b271b57d9554e25d863e3df6ef03ddd480\",\n \"role\": \"writer\"\n }\n ]\n}"
}
},
"401": {
"description": "Unauthorized: The accessToken is invalid, or has been revoked."
}
}
}
},
"/users/{authorId}/posts": {
"post": {
"summary": "Creating a post",
"description": "Creates a post on the authenticated user’s profile.",
"parameters": [
{
"name": "authorId",
"in": "path",
"description": "The userId of the post’s author",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"description": "Create post JSON body",
"schema": {
"properties": {
"title": {
"type": "string",
"description": "The title of the post. Note that this title is used for SEO and when rendering the post as a listing, but will not appear in the actual post—for that, the title must be specified in the content field as well. Titles longer than 100 characters will be ignored. In that case, a title will be synthesized from the first content in the post when it is published."
},
"contentFormat": {
"type": "string",
"description": "The format of the \"content\" field. There are two valid values, \"html\", and \"markdown\""
},
"content": {
"type": "string",
"description": "The body of the post, in a valid, semantic, HTML fragment, or Markdown. Further markups may be supported in the future. For a full list of accepted HTML tags, see here. If you want your title to appear on the post page, you must also include it as part of the post content."
},
"tags": {
"type": "string",
"items": {
"type": "string"
},
"description": "Tags to classify the post. Only the first three will be used. Tags longer than 25 characters will be ignored."
},
"canonicalUrl": {
"type": "string",
"description": "The original home of this content, if it was originally published elsewhere."
},
"publishStatus": {
"type": "string",
"description": "The status of the post. Valid values are “public”, “draft”, or “unlisted”. The default is “public”.",
"enum": [
"public",
"draft",
"unlisted"
]
},
"license": {
"type": "string",
"description": "The license of the post. Valid values are “all-rights-reserved”, “cc-40-by”, “cc-40-by-sa”, “cc-40-by-nd”, “cc-40-by-nc”, “cc-40-by-nc-nd”, “cc-40-by-nc-sa”, “cc-40-zero”, “public-domain”. The default is “all-rights-reserved”.",
"enum": [
"all-rights-reserved",
"cc-40-by",
"cc-40-by-sa",
"cc-40-by-nd",
"cc-40-by-nc",
"cc-40-by-nc-nd",
"cc-40-by-nc-sa",
"cc-40-zero",
"public-domain"
]
}
}
},
"required": true
}
],
"responses": {
"200": {
"description": "a post object response within a data envelope.",
"schema": {
"properties": {
"data": {
"description": "a post object within a data envelope",
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for the post."
},
"title": {
"type": "string",
"description": "The post’s title"
},
"authorId": {
"type": "string",
"description": "The userId of the post’s author"
},
"tags": {
"type": "string",
"description": "The post’s tags"
},
"url": {
"type": "string",
"description": "The URL of the post on Medium"
},
"canonicalUrl": {
"type": "string",
"description": "The canonical URL of the post. If canonicalUrl was not specified in the creation of the post, this field will not be present."
},
"publishStatus": {
"type": "string",
"description": "The publish status of the post."
},
"publishedAt": {
"type": "string",
"description": "The post’s published date. If created as a draft, this field will not be present."
},
"license": {
"type": "string",
"description": "The license of the post."
},
"licenseUrl": {
"type": "string",
"description": "The URL to the license of the post."
}
}
}
}
},
"examples": {
"application/json": "{\n \"data\": {\n \"id\": \"e6f36a\",\n \"title\": \"Liverpool FC\",\n \"authorId\": \"5303d74c64f66366f00cb9b2a94f3251bf5\",\n \"tags\": [\"football\", \"sport\", \"Liverpool\"],\n \"url\": \"https://medium.com/@majelbstoat/liverpool-fc-e6f36a\",\n \"canonicalUrl\": \"http://jamietalbot.com/posts/liverpool-fc\",\n \"publishStatus\": \"public\",\n \"publishedAt\": 1442286338435,\n \"license\": \"all-rights-reserved\",\n \"licenseUrl\": \"https://medium.com/policy/9db0094a1e0f\"\n }\n}"
}
},
"400": {
"description": "Bad Request: Required fields were invalid, not specified."
},
"401": {
"description": "Unauthorized: The access token is invalid or has been revoked."
},
"403": {
"description": "Forbidden: The user does not have permission to publish, or the authorId in the request path points to wrong/non-existent user."
}
}
}
},
"/publications/{publicationId}/posts": {
"post": {
"summary": "Creating a post under a publication",
"description": "This API allows creating a post and associating it with a publication on Medium",
"parameters": [
{
"name": "publicationId",
"in": "path",
"description": "ID of the publication this post was created under. This matches the publication ID requested in the URL of the request",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"description": "Create post JSON body",
"schema": {
"properties": {
"title": {
"type": "string",
"description": "The title of the post. Note that this title is used for SEO and when rendering the post as a listing, but will not appear in the actual post—for that, the title must be specified in the content field as well. Titles longer than 100 characters will be ignored. In that case, a title will be synthesized from the first content in the post when it is published."
},
"contentFormat": {
"type": "string",
"description": "The format of the \"content\" field. There are two valid values, \"html\", and \"markdown\""
},
"content": {
"type": "string",
"description": "The body of the post, in a valid, semantic, HTML fragment, or Markdown. Further markups may be supported in the future. For a full list of accepted HTML tags, see here. If you want your title to appear on the post page, you must also include it as part of the post content."
},
"tags": {
"type": "string",
"items": {
"type": "string"
},
"description": "Tags to classify the post. Only the first three will be used. Tags longer than 25 characters will be ignored."
},
"canonicalUrl": {
"type": "string",
"description": "The original home of this content, if it was originally published elsewhere."
},
"publishStatus": {
"type": "string",
"description": "The status of the post. Valid values are “public”, “draft”, or “unlisted”. The default is “public”.",
"enum": [
"public",
"draft",
"unlisted"
]
},
"license": {
"type": "string",
"description": "The license of the post. Valid values are “all-rights-reserved”, “cc-40-by”, “cc-40-by-sa”, “cc-40-by-nd”, “cc-40-by-nc”, “cc-40-by-nc-nd”, “cc-40-by-nc-sa”, “cc-40-zero”, “public-domain”. The default is “all-rights-reserved”.",
"enum": [
"all-rights-reserved",
"cc-40-by",
"cc-40-by-sa",
"cc-40-by-nd",
"cc-40-by-nc",
"cc-40-by-nc-nd",
"cc-40-by-nc-sa",
"cc-40-zero",
"public-domain"
]
}
}
},
"required": true
}
],
"responses": {
"200": {
"description": "a post object response within a data envelope.",
"schema": {
"properties": {
"data": {
"description": "a post object within a data envelope",
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for the post."
},
"title": {
"type": "string",
"description": "The post’s title"
},
"authorId": {
"type": "string",
"description": "The userId of the post’s author"
},
"tags": {
"type": "string",
"description": "The post’s tags"
},
"url": {
"type": "string",
"description": "The URL of the post on Medium"
},
"canonicalUrl": {
"type": "string",
"description": "The canonical URL of the post. If canonicalUrl was not specified in the creation of the post, this field will not be present."
},
"publishStatus": {
"type": "string",
"description": "The publish status of the post."
},
"publishedAt": {
"type": "string",
"description": "The post’s published date. If created as a draft, this field will not be present."
},
"license": {
"type": "string",
"description": "The license of the post."
},
"licenseUrl": {
"type": "string",
"description": "The URL to the license of the post."
}
}
}
}
},
"examples": {
"application/json": "{\n \"data\": {\n \"id\": \"e6f36a\",\n \"title\": \"Liverpool FC\",\n \"authorId\": \"5303d74c64f66366f00cb9b2a94f3251bf5\",\n \"tags\": [\"football\", \"sport\", \"Liverpool\"],\n \"url\": \"https://medium.com/@majelbstoat/liverpool-fc-e6f36a\",\n \"canonicalUrl\": \"http://jamietalbot.com/posts/liverpool-fc\",\n \"publishStatus\": \"public\",\n \"publishedAt\": 1442286338435,\n \"license\": \"all-rights-reserved\",\n \"licenseUrl\": \"https://medium.com/policy/9db0094a1e0f\"\n }\n}"
}
},
"400": {
"description": "Bad Request: Required fields were invalid, not specified."
},
"401": {
"description": "Unauthorized: The access token is invalid or has been revoked."
},
"403": {
"description": "Forbidden: The publicationId in request path doesn’t point to a publication that the user can publish into."
}
}
}
},
"/images": {
"post": {
"summary": "Uploading an image",
"description": "Medium will automatically side-load any images specified by the src attribute on an <img> tag in post content when creating a post. However, if you are building a desktop integration and have local image files that you wish to send, you may use the images endpoint.",
"responses": {
"200": {
"description": "an Image object within a data envelope.",
"schema": {
"properties": {
"data": {
"description": "an image object within a data envelope",
"properties": {
"url": {
"type": "string",
"description": "The URL of the image."
},
"md5": {
"type": "string",
"description": "An MD5 hash of the image data."
}
}
}
}
},
"examples": {
"application/json": "{\n \"data\": {\n \"url\": \"https://images.medium.com/0*fkfQiTzT7TlUGGyI.png\",\n \"md5\": \"fkfQiTzT7TlUGGyI\"\n }\n}"
}
}
}
}
}
},
"definitions": {
"Contributor": {
"properties": {
"publicationId": {
"type": "string",
"description": "An ID for the publication. This can be lifted from response of publications above"
},
"userId": {
"type": "string",
"description": "A user ID of the contributor."
},
"role": {
"type": "string",
"description": "Role of the user identified by userId in the publication identified by publicationId. 'editor' or 'writer'"
}
}
},
"ContributorListData": {
"properties": {
"data": {
"type": "array",
"items": {
"properties": {
"publicationId": {
"type": "string",
"description": "An ID for the publication. This can be lifted from response of publications above"
},
"userId": {
"type": "string",
"description": "A user ID of the contributor."
},
"role": {
"type": "string",
"description": "Role of the user identified by userId in the publication identified by publicationId. 'editor' or 'writer'"
}
}
},
"description": "a list of contributor objects within a data envelope"
}
}
},
"Image": {
"properties": {
"url": {
"type": "string",
"description": "The URL of the image."
},
"md5": {
"type": "string",
"description": "An MD5 hash of the image data."
}
}
},
"ImageData": {
"properties": {
"data": {
"description": "an image object within a data envelope",
"properties": {
"url": {
"type": "string",
"description": "The URL of the image."
},
"md5": {
"type": "string",
"description": "An MD5 hash of the image data."
}
}
}
}
},
"Post": {
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for the post."
},
"title": {
"type": "string",
"description": "The post’s title"
},
"authorId": {
"type": "string",
"description": "The userId of the post’s author"
},
"tags": {
"type": "string",
"description": "The post’s tags"
},
"url": {
"type": "string",
"description": "The URL of the post on Medium"
},
"canonicalUrl": {
"type": "string",
"description": "The canonical URL of the post. If canonicalUrl was not specified in the creation of the post, this field will not be present."
},
"publishStatus": {
"type": "string",
"description": "The publish status of the post."
},
"publishedAt": {
"type": "string",
"description": "The post’s published date. If created as a draft, this field will not be present."
},
"license": {
"type": "string",
"description": "The license of the post."
},
"licenseUrl": {
"type": "string",
"description": "The URL to the license of the post."
}
}
},
"PostData": {
"properties": {
"data": {
"description": "a post object within a data envelope",
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for the post."
},
"title": {
"type": "string",
"description": "The post’s title"
},
"authorId": {
"type": "string",
"description": "The userId of the post’s author"
},
"tags": {
"type": "string",
"description": "The post’s tags"
},
"url": {
"type": "string",
"description": "The URL of the post on Medium"
},
"canonicalUrl": {
"type": "string",
"description": "The canonical URL of the post. If canonicalUrl was not specified in the creation of the post, this field will not be present."
},
"publishStatus": {
"type": "string",
"description": "The publish status of the post."
},
"publishedAt": {
"type": "string",
"description": "The post’s published date. If created as a draft, this field will not be present."
},
"license": {
"type": "string",
"description": "The license of the post."
},
"licenseUrl": {
"type": "string",
"description": "The URL to the license of the post."
}
}
}
}
},
"PostRequest": {
"properties": {
"title": {
"type": "string",
"description": "The title of the post. Note that this title is used for SEO and when rendering the post as a listing, but will not appear in the actual post—for that, the title must be specified in the content field as well. Titles longer than 100 characters will be ignored. In that case, a title will be synthesized from the first content in the post when it is published."
},
"contentFormat": {
"type": "string",
"description": "The format of the \"content\" field. There are two valid values, \"html\", and \"markdown\""
},
"content": {
"type": "string",
"description": "The body of the post, in a valid, semantic, HTML fragment, or Markdown. Further markups may be supported in the future. For a full list of accepted HTML tags, see here. If you want your title to appear on the post page, you must also include it as part of the post content."
},
"tags": {
"type": "string",
"items": {
"type": "string"
},
"description": "Tags to classify the post. Only the first three will be used. Tags longer than 25 characters will be ignored."
},
"canonicalUrl": {
"type": "string",
"description": "The original home of this content, if it was originally published elsewhere."
},
"publishStatus": {
"type": "string",
"description": "The status of the post. Valid values are “public”, “draft”, or “unlisted”. The default is “public”.",
"enum": [
"public",
"draft",
"unlisted"
]
},
"license": {
"type": "string",
"description": "The license of the post. Valid values are “all-rights-reserved”, “cc-40-by”, “cc-40-by-sa”, “cc-40-by-nd”, “cc-40-by-nc”, “cc-40-by-nc-nd”, “cc-40-by-nc-sa”, “cc-40-zero”, “public-domain”. The default is “all-rights-reserved”.",
"enum": [
"all-rights-reserved",
"cc-40-by",
"cc-40-by-sa",
"cc-40-by-nd",
"cc-40-by-nc",
"cc-40-by-nc-nd",
"cc-40-by-nc-sa",
"cc-40-zero",
"public-domain"
]
}
}
},
"Publication": {
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for the publication."
},
"name": {
"type": "string",
"description": "The publication’s name on Medium."
},
"description": {
"type": "string",
"description": "Short description of the publication"
},
"url": {
"type": "string",
"description": "The URL to the publication’s homepage"
},
"imageUrl": {
"type": "string",
"description": "The URL to the publication’s image/logo"
}
}
},
"PublicationListData": {
"properties": {
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for the publication."
},
"name": {
"type": "string",
"description": "The publication’s name on Medium."
},
"description": {
"type": "string",
"description": "Short description of the publication"
},
"url": {
"type": "string",
"description": "The URL to the publication’s homepage"
},
"imageUrl": {
"type": "string",
"description": "The URL to the publication’s image/logo"
}
}
},
"description": "a list of publication objects within a data envelope"
}
}
},
"User": {
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for the user."
},
"username": {
"type": "string",
"description": "The user’s username on Medium."
},
"name": {
"type": "string",
"description": "The user’s name on Medium."
},
"url": {
"type": "string",
"description": "The URL to the user’s profile on Medium."
},
"imageUrl": {
"type": "string",
"description": "The URL to the user’s avatar on Medium."
}
}
},
"UserData": {
"properties": {
"data": {
"description": "a user object within a data envelope",
"properties": {
"id": {
"type": "string",
"description": "A unique identifier for the user."
},
"username": {
"type": "string",
"description": "The user’s username on Medium."
},
"name": {
"type": "string",
"description": "The user’s name on Medium."
},
"url": {
"type": "string",
"description": "The URL to the user’s profile on Medium."
},
"imageUrl": {
"type": "string",
"description": "The URL to the user’s avatar on Medium."
}
}
}
}
}
}
}