swagger: "2.0" info: description: | Medium’s unofficial API documentation using OpenAPI specification. # Official API Official API document can also be viewed for most up to date API spec at [https://github.com/Medium/medium-api-docs](https://github.com/Medium/medium-api-docs). Developer Blog - [Welcome to the Medium API](https://medium.com/blog/welcome-to-the-medium-api-3418f956552) version: "1.0.0" title: Medium.com - Unofficial API Spec termsOfService: https://medium.com/@feerst/2b405a832a2f contact: name: Hossain Khan url: https://github.com/amardeshbd/medium-api-specification # All requests are made to endpoints beginning: https://api.medium.com/v1 host: api.medium.com basePath: /v1 # All requests must be secure, i.e. https, not http. schemes: - https # List of security definitions used for API access securityDefinitions: BearerToken: type: apiKey description: | Self-issued access tokens (described in user-facing copy as integration tokens) are explicitly designed for desktop integrations where implementing browser-based authentication is non-trivial, or software like plugins where it is impossible to secure a client secret. You should not request that a user give you an integration token if you don’t meet these criteria. Users will be cautioned within Medium to treat integration tokens like passwords, and dissuaded from making them generally available. Users can generate an access token from the [Settings page](https://medium.com/me/settings) of their Medium account. You should instruct your user to visit this URL and generate an integration token from the Integration Tokens section. You should suggest a description for this token - typically the name of your product or feature - and use it consistently for all users. Self-issued access tokens currently grant the `basicProfile` and `publishPost` scope. A future iteration of the API will require a user to select the scope they wish to grant access to. Self-issued access tokens do not expire, though they may be revoked by the user at any time. name: Authorization in: header OauthSecurity: type: oauth2 description: First you must register an application on Medium. Then we will supply you a clientId and a clientSecret with which you may access Medium’s API. Each integration should have its own clientId and clientSecret. The clientSecret should be treated like a password and stored securely. authorizationUrl: https://medium.com/m/oauth/authorize tokenUrl: https://medium.com/v1/tokens flow: accessCode scopes: basicProfile: Grants basic access to a user’s profile (not including their email). listPublications: Grants the ability to list publications related to the user. publishPost: Grants the ability to publish a post to the user’s profile. uploadImage: | Grants the ability to upload an image for use within a Medium post. NOTE - This is an **extended permission**. Integrations are not permitted to request extended scope from users without explicit prior permission from Medium. Attempting to request these permissions through the standard user authentication flow will result in an error if extended scope has not been authorized for an integration. # format of the responses to the client (Accepts) produces: - application/json paths: /me: get: summary: User details description: Returns details of the user who has granted permission to the application. tags: - Users security: - BearerToken: [] - OauthSecurity: - basicProfile produces: - application/json responses: 200: description: OK schema: $ref: "#/definitions/UserResponse" 401: description: The `accessToken` is invalid or has been revoked. /users/{userId}/publications: get: summary: User's publications description: Returns a full list of publications that the user is related to in some way. This includes all publications the user is subscribed to, writes to, or edits. tags: - Publications security: - BearerToken: [] - OauthSecurity: - listPublications produces: - application/json parameters: - in: path name: userId description: A unique identifier for the user. required: true type: string responses: 200: description: OK schema: $ref: "#/definitions/PublicationResponse" 401: description: The `accessToken` is invalid, lacks the `listPublications` scope or has been revoked. 403: description: The request attempts to list publications for another user. /publications/{publicationId}/contributors: get: summary: Contributors of Publication description: This endpoint returns a list of contributors for a given publication. In other words, a list of Medium users who are allowed to publish under a publication, as well as a description of their exact role in the publication (for now, either an editor or a writer). tags: - Publications - Users security: - BearerToken: [] - OauthSecurity: - listPublications produces: - application/json parameters: - in: path name: publicationId description: A unique identifier for the publication. required: true type: string responses: 200: description: OK schema: $ref: "#/definitions/ContibutorResponse" 401: description: The `accessToken` is invalid or has been revoked. /users/{authorId}/posts: post: summary: Create User Post description: Creates a post on the authenticated user’s profile. tags: - Users - Posts security: - BearerToken: [] - OauthSecurity: - publishPost produces: - application/json consumes: - application/json parameters: - in: path name: authorId description: authorId is the user id of the authenticated user. required: true type: string - in: body name: body description: Creates a post for user. required: true schema: $ref: "#/definitions/Post" responses: 200: description: OK schema: $ref: '#/definitions/PostDetails' 400: description: Required fields were invalid, not specified. 401: description: The `accessToken` is invalid or has been revoked. 403: description: 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: Create Publication Post description: | creating a post and associating it with a publication on Medium. The request also shows this association, considering posts a collection of resources under a publication There are additional rules around publishing that each request to this API must respect: - If the authenticated user is an 'editor' for the publication, they can create posts with any publish status. Posts published as 'public' or 'unlisted' will appear in collection immediately, while posts created as 'draft' will remain in pending state under publication. - If the authenticated user is a 'writer' for the chosen publication, they can only create a post as a 'draft'. That post will remain in pending state under publication until an editor for the publication approves it. - If the authenticated user is neither a 'writer' nor an 'editor', they are not allowed to create any posts in a publication. tags: - Posts - Publications security: - BearerToken: [] - OauthSecurity: - publishPost produces: - application/json consumes: - application/json parameters: - in: path name: publicationId description: Here publicationId is the id of the publication the post is being created under. The publicationId can be acquired from the API for listing user’s publications. required: true type: string - in: body name: body description: Creates a post for publication. required: true schema: $ref: "#/definitions/Post" responses: 200: description: OK schema: $ref: '#/definitions/PostDetails' 400: description: Required fields were invalid, not specified. 401: description: The `accessToken` is invalid or has been revoked. 403: description: The `publicationId` in request path doesn’t point to a publication that the user can publish into. # TODO Missing API for image endpoint # See https://github.com/amardeshbd/medium-api-specification/issues/7 definitions: UserResponse: type: object title: User Container description: Container object for user info properties: data: $ref: "#/definitions/User" example: data: id: "5303d74c64f66366f00cb9b2a94f3251bf5" username: "majelbstoat" name: "Jamie Talbot" url: "https://medium.com/@majelbstoat" imageUrl: "https://images.medium.com/0*fkfQiTzT7TlUGGyI.png" User: type: object 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 example: id: "5303d74c64f66366f00cb9b2a94f3251bf5" username: "majelbstoat" name: "Jamie Talbot" url: "https://medium.com/@majelbstoat" imageUrl: "https://images.medium.com/0*fkfQiTzT7TlUGGyI.png" PublicationResponse: title: Publication List Container description: Container object for publication list. properties: data: type: array items: $ref: "#/definitions/Publication" example: 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" Publication: type: object title: Publication Info description: Publications provide a way for authors to work collaboratively within a common narrative framework, brand or point of view. 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 example: 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" ContibutorResponse: title: Contributors list for a publication description: list of contributors for a given publication properties: data: type: array items: $ref: "#/definitions/Contibutor" example: 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" Contibutor: type: object title: Contributor description: Contibutor 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* Post: type: object title: Post required: - title - contentFormat - content 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: array 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 default: public enum: - public - draft - unlisted description: The status of the post. Valid values are `public`, `draft`, or `unlisted`. The default is `public`. license: type: string default: 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 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`. example: title: "Liverpool FC" contentFormat: "html" content: "

Liverpool FC

You’ll never walk alone.

" canonicalUrl: "http://jamietalbot.com/posts/liverpool-fc" tags: - "football" - "sport" - "Liverpool" publishStatus: "public" PostDetails: title: Post Details description: Details of 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: array items: 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 format: date description: The post’s published date. If created as a draft, this field will not be present. license: type: string 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 description: The license of the post. licenseUrl: type: string description: The URL to the license of the post. example: 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"