openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key File API
  description: Complete public API for accessing resources in your Ashby instance. Includes applications, candidates, jobs, interviews, offers, surveys, custom fields, organization metadata, files, reports, approvals, and webhooks.
  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: HTTP Basic Auth. Send your Ashby API key as the username and leave the password blank.
    WebhookSignature:
      type: apiKey
      in: header
      name: Ashby-Signature
      description: HMAC-SHA256 signature of the webhook payload, used to verify webhook authenticity.