openapi: 3.2.0
info:
  title: Street Open Documents API
  description: Build on top of the UKs most advanced Estate Agency software.
  version: '1.0'
  contact:
    name: Street API Development Team
    url: https://street.co.uk
    email: apis@street.co.uk
servers:
- url: https://street.co.uk/open-api/v1
  description: Production.
- url: https://demo.street.co.uk/open-api/v1
  description: Testing.
security:
- your-api-token: []
tags:
- name: Documents
  description: Documents endpoints for this API.
paths:
  /documents:
    parameters: []
    post:
      operationId: post-documents
      summary: Create a Document
      responses:
        '201':
          description: Created.
          content:
            application/vnd.api+json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Media'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '406':
          $ref: '#/components/responses/406'
        '409':
          $ref: '#/components/responses/409'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: object
                  required:
                  - type
                  - attributes
                  - relationships
                  properties:
                    type:
                      type: string
                      enum:
                      - document
                    attributes:
                      type: object
                      required:
                      - file_url
                      - title
                      properties:
                        file_url:
                          type: string
                          format: uri
                          description: 'The endpoint will only accept the following filetypes: PDF, JPG, PNG.'
                        title:
                          type: string
                        description:
                          type:
                          - string
                          - 'null'
                        is_public:
                          type:
                          - boolean
                          - 'null'
                          description: Indicates whether the document is public. This value will be ignored if it's determined that the document cannot be made public.
                          default: false
                        key:
                          type:
                          - string
                          - 'null'
                          enum:
                          - api_tenancy_guide
                          - api_landlord_offer_letter
                          - api_tenancy_agreement
                          - api_tenant_guarantor_reference_form
                          - api_tenant_guarantor_reference_report
                          - api_tenant_guarantor_id_document
                          pattern: ^[a-z_]*$
                          example: api_tenancy_guide
                    relationships:
                      oneOf:
                      - $ref: '#/components/schemas/PropertyRelated'
                      - $ref: '#/components/schemas/SalesApplicantRelated'
                      - $ref: '#/components/schemas/LettingsApplicantRelated'
      description: "This endpoint allows you to create a `Document` attached to an entity by providing a publically accessible URL for the file.\n        In addition you can add relevant information such as a title and description of the file."
      tags:
      - Documents
      x-internal: false
components:
  responses:
    '406':
      description: The HTTP 406 Not Acceptable client error response code indicates that the server cannot produce a response matching the list of acceptable values defined in the request's proactive content negotiation headers, and that the server is unwilling to supply a default representation.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '403':
      description: The HTTP 403 Forbidden response status code indicates that the server understands the request but refuses to authorize it.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '409':
      description: The HTTP 409 Conflict response status code indicates a request conflict with the current state of the target resource.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '500':
      description: The HTTP 500 Internal Server Error server error response code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiMultiErrorResponseBody'
    '401':
      description: The HTTP 401 Unauthorized response status code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '415':
      description: The HTTP 415 Unsupported Media Type client error response code indicates that the server refuses to accept the request because the payload format is in an unsupported format.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '400':
      description: The HTTP 400 Bad Request response status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiMultiErrorResponseBody'
  schemas:
    jsonApiErrorResponseBody:
      title: JSON:API Error Response Body
      description: Response body for JSON:API errors, containing an array of `errors` in place of the `data` property provided in JSON:API success responses. Used for non-400/500 error codes where only a single error is expected.
      type: object
      properties:
        meta:
          type: object
        source:
          type: object
          description: The primary source of the conflict for 409 responses.
          properties:
            pointer:
              type: string
              description: JSON Pointer to the conflicting request value.
            parameter:
              type: string
              description: URI parameter related to the conflict.
        errors:
          description: An array of error objects providing additional information about problems encountered while processing the request.
          type: array
          maxItems: 1
          items:
            $ref: '#/components/schemas/jsonApiError'
      required:
      - errors
    PropertyRelated:
      title: Property (related)
      type: object
      additionalProperties: false
      properties:
        property:
          type: object
          properties:
            data:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - property
                id:
                  type: string
                  format: uuid
    DefaultMedia:
      title: DefaultMedia
      type: object
      properties:
        name:
          type: string
          example: p045126_01
        order:
          type: integer
          example: 1
        is_featured:
          type:
          - boolean
          - 'null'
          default: false
        include_in_listing:
          type:
          - boolean
          - 'null'
          default: false
        feature_index:
          type:
          - 'null'
          - integer
        title:
          type:
          - 'null'
          - string
        collection:
          type: string
          example: general
    ImageMedia:
      title: Image
      type: object
      properties:
        media_type:
          type: string
          description: A user defined type to enable categorizing generic media items
          enum:
          - image
        url:
          type: string
          example: https://ik.imagekit.io/street/street-live/properties/general/787110/p045126_01.jpg
          format: uri
    LettingsApplicantRelated:
      title: Lettings Applicant (related)
      type: object
      additionalProperties: false
      properties:
        lettings_applicant:
          type: object
          properties:
            data:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - lettingsApplicant
                id:
                  type: string
                  format: uuid
    PdfMedia:
      title: PDF
      type: object
      properties:
        media_type:
          type: string
          description: A user defined type to enable categorizing generic media items
          enum:
          - pdf
        url:
          type: string
          example: https://ik.imagekit.io/street/street-live/properties/general/787110/p045126_01.pdf
          format: uri
      required:
      - media_type
    SalesApplicantRelated:
      title: Sales Applicant (related)
      type: object
      additionalProperties: false
      properties:
        sales_applicant:
          type: object
          properties:
            data:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - salesApplicant
                id:
                  type: string
                  format: uuid
    jsonApiError:
      title: JSON:API Error Object
      description: A JSON:API object representing a single error.
      type: object
      properties:
        title:
          type: string
        detail:
          type: string
        code:
          type: string
        source:
          type: object
          description: An object containing references to the primary source of the error.
          properties:
            pointer:
              type: string
              description: A JSON Pointer to the value in the request document that caused the error.
            parameter:
              type: string
              description: A string indicating which URI query parameter caused the error.
      required:
      - title
      examples:
      - title: 401 Unauthorized
        detail: The requester is not authorized to access the resource.
        code: '401'
    Media:
      title: Media
      x-tags:
      - Media
      allOf:
      - $ref: '#/components/schemas/BaseModel'
      - type: object
        properties:
          type:
            type: string
            enum:
            - media
          attributes:
            $ref: '#/components/schemas/MediaAttributes'
    BaseModel:
      title: Base Model
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
        attributes:
          type: object
        relationships:
          type: object
    jsonApiMultiErrorResponseBody:
      title: JSON:API Multi-Error Response Body
      description: Response body for JSON:API errors that may contain multiple error objects (400 Bad Request and 500 Internal Server Error).
      type: object
      properties:
        meta:
          type: object
        errors:
          description: An array of error objects providing additional information about problems encountered while processing the request.
          type: array
          items:
            $ref: '#/components/schemas/jsonApiError'
      required:
      - errors
    MediaAttributes:
      title: MediaAttributes
      allOf:
      - $ref: '#/components/schemas/DefaultMedia'
      - oneOf:
        - $ref: '#/components/schemas/ImageMedia'
        - $ref: '#/components/schemas/PdfMedia'
  securitySchemes:
    your-api-token:
      type: http
      scheme: bearer
x-ext-urls: {}