docs/medium-api-v1-swagger.yaml
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:
$ref: "#/definitions/UserData"
examples:
application/json: |-
{
"data": {
"id": "5303d74c64f66366f00cb9b2a94f3251bf5",
"username": "majelbstoat",
"name": "Jamie Talbot",
"url": "https://medium.com/@majelbstoat",
"imageUrl": "https://images.medium.com/0*fkfQiTzT7TlUGGyI.png"
}
}
"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:
$ref: "#/definitions/PublicationListData"
examples:
application/json: |-
{
"data": [
{
"id": "b969ac62a46b",
"name": "About Medium",
"description": "What is this thing and how does it work?",
"url": "https://medium.com/about",
"imageUrl": "https://cdn-images-1.medium.com/fit/c/200/200/0*ae1jbP_od0W6EulE.jpeg"
},
{
"id": "b45573563f5a",
"name": "Developers",
"description": "Medium’s Developer resources",
"url": "https://medium.com/developers",
"imageUrl": "https://cdn-images-1.medium.com/fit/c/200/200/1*ccokMT4VXmDDO1EoQQHkzg@2x.png"
}
]
}
"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:
$ref: "#/definitions/ContributorListData"
examples:
application/json: |-
{
"data": [
{
"publicationId": "b45573563f5a",
"userId": "13a06af8f81849c64dafbce822cbafbfab7ed7cecf82135bca946807ea351290d",
"role": "editor"
},
{
"publicationId": "b45573563f5a",
"userId": "1c9c63b15b874d3e354340b7d7458d55e1dda0f6470074df1cc99608a372866ac",
"role": "editor"
},
{
"publicationId": "b45573563f5a",
"userId": "1cc07499453463518b77d31650c0b53609dc973ad8ebd33690c7be9236e9384ad",
"role": "editor"
},
{
"publicationId": "b45573563f5a",
"userId": "196f70942410555f4b3030debc4f199a0d5a0309a7b9df96c57b8ec6e4b5f11d7",
"role": "writer"
},
{
"publicationId": "b45573563f5a",
"userId": "14d4a581f21ff537d245461b8ff2ae9b271b57d9554e25d863e3df6ef03ddd480",
"role": "writer"
}
]
}
"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:
$ref: "#/definitions/PostRequest"
required: true
responses:
"200":
description: "a post object response within a data envelope."
schema:
$ref: "#/definitions/PostData"
examples:
application/json: |-
{
"data": {
"id": "e6f36a",
"title": "Liverpool FC",
"authorId": "5303d74c64f66366f00cb9b2a94f3251bf5",
"tags": ["football", "sport", "Liverpool"],
"url": "https://medium.com/@majelbstoat/liverpool-fc-e6f36a",
"canonicalUrl": "http://jamietalbot.com/posts/liverpool-fc",
"publishStatus": "public",
"publishedAt": 1442286338435,
"license": "all-rights-reserved",
"licenseUrl": "https://medium.com/policy/9db0094a1e0f"
}
}
"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:
$ref: "#/definitions/PostRequest"
required: true
responses:
"200":
description: "a post object response within a data envelope."
schema:
$ref: "#/definitions/PostData"
examples:
application/json: |-
{
"data": {
"id": "e6f36a",
"title": "Liverpool FC",
"authorId": "5303d74c64f66366f00cb9b2a94f3251bf5",
"tags": ["football", "sport", "Liverpool"],
"url": "https://medium.com/@majelbstoat/liverpool-fc-e6f36a",
"canonicalUrl": "http://jamietalbot.com/posts/liverpool-fc",
"publishStatus": "public",
"publishedAt": 1442286338435,
"license": "all-rights-reserved",
"licenseUrl": "https://medium.com/policy/9db0094a1e0f"
}
}
"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:
$ref: "#/definitions/ImageData"
examples:
application/json: |-
{
"data": {
"url": "https://images.medium.com/0*fkfQiTzT7TlUGGyI.png",
"md5": "fkfQiTzT7TlUGGyI"
}
}
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:
$ref: "#/definitions/Contributor"
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
$ref: "#/definitions/Image"
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
$ref: "#/definitions/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:
$ref: "#/definitions/Publication"
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
$ref: "#/definitions/User"