medium-api-specification.yaml

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: "<h1>Liverpool FC</h1><p>You’ll never walk alone.</p>"
      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"