Skip to main content

Try the live demo!

Search

Serve Media

Public media is served without authentication. Private media requires authentication with access to the linked record, or a valid signed URL. Private media not yet attached to a record is served only to the user who uploaded it.

GET /uploads/{uuid}

Public media is served without authentication. Private media requires authentication with access to the linked record, or a valid signed URL. Private media not yet attached to a record is served only to the user who uploaded it.

Authentication

Use an agent API key and secret.

Parameters

Name Location Type Required Description
uuid path string Yes Media UUID. Prefix with thumb_ to get an image thumbnail.
sig query string No Signature of a signed media URL. Used together with exp.
exp query integer No Expiry unix timestamp of a signed media URL.
download query string No Pass 1 to force a download instead of inline display.

Responses

200

File content. With the S3 upload provider the server responds with a 302 redirect to the file instead.

Content type: */*.

Field Type Required
body string (binary)

302

Redirect to the file in S3 storage

400

Invalid request

Content type: application/json.

All fields are optional.

Field Type Description
status string example: "error"
message string Error message example: "Invalid request"
data unspecified Additional error data nullable: true
error_type string (enum) enum: ["GeneralException", "PermissionException", "InputException", "DataException", "NetworkException", "NotFoundException", "ConflictException", "UnauthorizedException", "RateLimitException"]

401

Unauthorized

Content type: application/json.

Response fields match the 400 response.

403

Permission denied

Content type: application/json.

Response fields match the 400 response.

404

Not found

Content type: application/json.

Response fields match the 400 response.

429

Rate limit exceeded

Content type: application/json.

Response fields match the 400 response.

500

Internal server error

Content type: application/json.

Response fields match the 400 response.

Specification

Download the complete OpenAPI specification.

OpenAPI definition for this endpoint
openapi: 3.0.0
info:
  title: libredesk API
  description: >-
    REST API documentation for libredesk helpdesk system.


    ## Authentication


    The libredesk API supports two authentication methods:


    ### 1. Basic Authentication

    Use your API key and secret with Basic authentication:

    ```

    Authorization: Basic <base64_encoded_api_key:api_secret>

    ```


    ### 2. Token Authentication  

    Use your API key and secret with token authentication:

    ```

    Authorization: token api_key:api_secret

    ```


    To obtain API credentials, generate them from your agent profile in the
    libredesk dashboard.
  version: 1.0.0
servers:
  - url: http://localhost:8080
    description: Local development server
security:
  - basicAuth: []
  - tokenAuth: []
paths:
  /uploads/{uuid}:
    get:
      tags:
        - Media
      summary: Serve Media
      description: >-
        Public media is served without authentication. Private media requires
        authentication with access to the linked record, or a valid signed URL.
        Private media not yet attached to a record is served only to the user
        who uploaded it.
      operationId: handleServeMedia
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
          description: Media UUID. Prefix with `thumb_` to get an image thumbnail.
        - name: sig
          in: query
          required: false
          schema:
            type: string
          description: Signature of a signed media URL. Used together with `exp`.
        - name: exp
          in: query
          required: false
          schema:
            type: integer
          description: Expiry unix timestamp of a signed media URL.
        - name: download
          in: query
          required: false
          schema:
            type: string
          description: Pass `1` to force a download instead of inline display.
      responses:
        '200':
          description: >-
            File content. With the S3 upload provider the server responds with a
            302 redirect to the file instead.
          content:
            '*/*':
              schema:
                type: string
                format: binary
        '302':
          description: Redirect to the file in S3 storage
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - basicAuth: []
        - tokenAuth: []
        - {}
components:
  schemas:
    ErrorResponse:
      type: object
      description: Error response format
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          description: Error message
          example: Invalid request
        data:
          nullable: true
          description: Additional error data
        error_type:
          type: string
          enum:
            - GeneralException
            - PermissionException
            - InputException
            - DataException
            - NetworkException
            - NotFoundException
            - ConflictException
            - UnauthorizedException
            - RateLimitException
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Basic authentication using base64 encoded API key and secret. Format:
        `Authorization: Basic <base64(api_key:api_secret)>`
    tokenAuth:
      type: apiKey
      name: Authorization
      in: header
      description: >-
        Token authentication using API key and secret. Format: `Authorization:
        token api_key:api_secret`

Was this article helpful?