Ashby File API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key File API
  description: The public API for accessing resources in your Ashby instance.
  contact:
    name: Ashby Support
    url: https://app.ashbyhq.com/support
    email: support@ashbyhq.com
servers:
- url: https://api.ashbyhq.com
security:
- BasicAuth: []
tags:
- name: File
paths:
  /file.info:
    post:
      summary: file.info
      description: 'Retrieve the url of a file associated with a candidate


        **Requires the [`candidatesRead`](authentication#permissions-fileinfo) permission.**


        **Please note** that running this with Ashby-generated demo data in an Ashby demo account can result in errors. We would recommend manually creating a test candidate in Ashby when trying out this endpoint.

        '
      operationId: fileInfo
      tags:
      - File
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fileHandle:
                  type: string
                  description: A file handle retrieved from the public API
                  example: 'eyJoYW5kbGUiOnsidHlwZSI6IkNhbmRpZGF0ZUZpbGUiLCJmaWxlSWQiOiIxNTk1ZTRmYy04MTQwLTQ1NGUtYTI1ZC04NTNiOTQ3ZWNmYzgiLCJvd25lcklkIjoiYmY5NGZlNmMtMjU3MS00NzQ1LWE1OWEtNTA5MjE3ODI3MDVlIn0sInNpZ25hdHVyZSI6IkFqclpjT0VlTXUwdWxLZlRCS05iMWRkbDdHcjVIWFVmZzNrS0NPL1dWWjg9IiwidmVyc2lvbiI6IjEilQ

                    '
              required:
              - fileHandle
      responses:
        '200':
          description: Responses for the file.info endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        type: object
                        properties:
                          url:
                            type: string
                            description: The url of the file
                            example: https://s3.amazonaws.com/...
                        required:
                        - url
                    required:
                    - results
                - title: Error response
                  $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /file.createFileUploadHandle:
    post:
      summary: file.createFileUploadHandle
      operationId: fileCreateFileUploadHandle
      description: "Creates a presigned upload URL that allows uploading a file directly to storage, bypassing the need to send file bytes through the API.\n\nBenefits over multipart upload:\n- **Reliability**: File bytes are uploaded directly to storage, avoiding timeouts and connection resets that can occur when proxying large files through the API.\n- **Compatibility**: Avoids issues with firewalls or proxies that block or scan multipart payloads containing binary content.\n- **Simplicity**: The follow-up call to, e.g., `candidate.uploadResume`, `candidate.uploadFile`, or `applicationForm.submit` is a plain `application/json` request rather than `multipart/form-data`.\n\n**Requires the [`candidatesWrite`](authentication#permissions-filecreatefileuploadhandle) permission.**\n\n**Usage flow:**\n\n1. Call `file.createFileUploadHandle` with the file metadata to get a presigned upload URL, form fields, and a handle.\n2. Upload the file directly to the returned `url` using a `multipart/form-data` POST request. Include all returned `fields` as form fields, and the file as the last field named `file`.\n3. Use the returned `handle` in a follow-up call:\n   - `candidate.uploadResume` with `{ candidateId, resumeHandle }` to attach a resume to a candidate.\n   - `candidate.uploadFile` with `{ candidateId, fileHandle }` to attach a file to a candidate.\n   - `applicationForm.submit` with `Content-Type: application/json`, where file field values in `fieldSubmissions` contain the handle string instead of a multipart file reference.\n\nThe presigned URL expires after 10 minutes. The `fileUploadContext` must be one of `CandidateResume`, `CandidateFiles`, or `ApplicationForm`.\n"
      tags:
      - File
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fileUploadContext:
                  type: string
                  enum:
                  - CandidateResume
                  - CandidateFiles
                  - ApplicationForm
                  description: The context for the file upload. Use `CandidateResume` for resume uploads, `CandidateFiles` for general file uploads, and `ApplicationForm` for file fields in application form submissions.
                filename:
                  type: string
                  description: The name of the file being uploaded, including extension.
                  example: resume.pdf
                contentType:
                  type: string
                  description: The MIME type of the file being uploaded.
                  example: application/pdf
                contentLength:
                  type: integer
                  description: The size of the file in bytes.
                  example: 102400
              required:
              - fileUploadContext
              - filename
              - contentType
              - contentLength
      responses:
        '200':
          description: Responses from the file.createFileUploadHandle endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        type: object
                        properties:
                          handle:
                            type: string
                            description: An encrypted handle to pass to `candidate.uploadResume` (as `resumeHandle`), `candidate.uploadFile` (as `fileHandle`), or `applicationForm.submit` (as the file field value in `fieldSubmissions`) after the file has been uploaded.
                          url:
                            type: string
                            description: The presigned URL to upload the file to via a `multipart/form-data` POST request.
                          fields:
                            type: object
                            additionalProperties:
                              type: string
                            description: Form fields that must be included in the multipart upload request to the presigned URL. Include these as form fields before the file field.
                        required:
                        - handle
                        - url
                        - fields
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: "Use HTTP Basic Auth to authenticate with our API. You must send your API key with every request. \nPut your API key as the basic auth username and leave the password blank.\n"
    WebhookSignature:
      type: apiKey
      in: header
      name: Ashby-Signature
      description: '[Optional] If you provide a secret token when configuring your webhook, this will be used to create a digest of the JSON payload sent with each webhook request.

        The digest will be included in the request under the `Ashby-Signature` http header.


        It will look like this:

        `Ashby-Signature: sha256=f3124911d2956f10aa3a49c43a88bdf13bba846e94f0ae2bd7c034f90239bd04`


        The part before the = indicates the algorithm that was used to compute the hash digest.

        '