openapi: 3.1.0
info:
  title: ServiceNow Attachment API
  description: >-
    The ServiceNow Attachment API enables uploading, retrieving, and deleting
    file attachments associated with records in ServiceNow tables. It supports
    uploading files via multipart form-data or binary streams and allows file
    sizes up to 1024 MB by default. Attachments can be queried by table name,
    record sys_id, or file metadata.
  version: 'Yokohama'
  contact:
    name: ServiceNow Support
    url: https://support.servicenow.com
  termsOfService: https://www.servicenow.com/terms-of-use.html
externalDocs:
  description: ServiceNow Attachment API Documentation
  url: https://www.servicenow.com/docs/bundle/yokohama-api-reference/page/integrate/inbound-rest/concept/c_AttachmentAPI.html
servers:
- url: https://{instance}.service-now.com/api/now
  description: ServiceNow Instance
  variables:
    instance:
      default: instance
      description: Your ServiceNow instance name
tags:
- name: Attachments
  description: >-
    Operations for uploading, retrieving, listing, and deleting file
    attachments on ServiceNow records.
security:
- basicAuth: []
- oauth2: []
paths:
  /attachment:
    get:
      operationId: listAttachments
      summary: Servicenow List Attachments
      description: >-
        Retrieves metadata for file attachments. Supports query filtering by
        table name, record sys_id, file name, and other attachment attributes.
      tags:
      - Attachments
      parameters:
      - name: sysparm_query
        in: query
        required: false
        description: >-
          Encoded query string to filter attachments. Common fields include
          table_name, table_sys_id, file_name, and content_type.
        schema:
          type: string
        example: 'table_name=incident^table_sys_id=abc123def456'
      - name: sysparm_limit
        in: query
        required: false
        description: Maximum number of attachment records to return.
        schema:
          type: integer
          minimum: 1
          default: 10000
        example: 10
      - name: sysparm_offset
        in: query
        required: false
        description: Starting record index for pagination.
        schema:
          type: integer
          minimum: 0
          default: 0
        example: 10
      responses:
        '200':
          description: >-
            Successful response returning attachment metadata records.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Attachment'
              examples:
                Listattachments200Example:
                  summary: Default listAttachments 200 response
                  x-microcks-default: true
                  value:
                    result:
                    - sys_id: '500123'
                      file_name: example_value
                      table_name: example_value
                      table_sys_id: '500123'
                      content_type: example_value
                      size_bytes: 10
                      size_compressed: 10
                      download_link: https://www.example.com
                      image_height: 10
                      image_width: 10
                      hash: example_value
                      state: example_value
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_created_by: example_value
                      sys_updated_on: '2026-01-15T10:30:00Z'
                      sys_updated_by: example_value
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listattachments401Example:
                  summary: Default listAttachments 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /attachment/{sys_id}:
    get:
      operationId: getAttachment
      summary: Servicenow Retrieve Attachment Metadata
      description: >-
        Retrieves metadata for a single attachment by its sys_id. Does not
        return the binary file content; use the file download endpoint instead.
      tags:
      - Attachments
      parameters:
      - $ref: '#/components/parameters/sysId'
      responses:
        '200':
          description: Successful response returning attachment metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Attachment'
              examples:
                Getattachment200Example:
                  summary: Default getAttachment 200 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      file_name: example_value
                      table_name: example_value
                      table_sys_id: '500123'
                      content_type: example_value
                      size_bytes: 10
                      size_compressed: 10
                      download_link: https://www.example.com
                      image_height: 10
                      image_width: 10
                      hash: example_value
                      state: example_value
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_created_by: example_value
                      sys_updated_on: '2026-01-15T10:30:00Z'
                      sys_updated_by: example_value
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getattachment401Example:
                  summary: Default getAttachment 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Attachment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getattachment404Example:
                  summary: Default getAttachment 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteAttachment
      summary: Servicenow Delete an Attachment
      description: >-
        Deletes an attachment and its associated file content from the
        ServiceNow instance.
      tags:
      - Attachments
      parameters:
      - $ref: '#/components/parameters/sysId'
      responses:
        '204':
          description: Attachment successfully deleted. No content returned.
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Deleteattachment401Example:
                  summary: Default deleteAttachment 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Attachment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Deleteattachment404Example:
                  summary: Default deleteAttachment 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /attachment/{sys_id}/file:
    get:
      operationId: downloadAttachmentFile
      summary: Servicenow Download Attachment File Content
      description: >-
        Downloads the binary file content of an attachment. The response
        Content-Type header reflects the original file type.
      tags:
      - Attachments
      parameters:
      - $ref: '#/components/parameters/sysId'
      responses:
        '200':
          description: Successful response returning the binary file content.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
              examples:
                Downloadattachmentfile200Example:
                  summary: Default downloadAttachmentFile 200 response
                  x-microcks-default: true
                  value: example_value
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Downloadattachmentfile401Example:
                  summary: Default downloadAttachmentFile 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Attachment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Downloadattachmentfile404Example:
                  summary: Default downloadAttachmentFile 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /attachment/file:
    post:
      operationId: uploadAttachmentBinary
      summary: Servicenow Upload a File Attachment via Binary Stream
      description: >-
        Uploads a file as a binary stream and attaches it to the specified
        table record. The Content-Type header should match the actual file
        type being uploaded.
      tags:
      - Attachments
      parameters:
      - name: table_name
        in: query
        required: true
        description: >-
          The name of the table to which the file is attached.
        schema:
          type: string
        example: incident
      - name: table_sys_id
        in: query
        required: true
        description: The sys_id of the record to which the file is attached.
        schema:
          type: string
        example: '500123'
      - name: file_name
        in: query
        required: true
        description: The name of the file including its extension.
        schema:
          type: string
        example: screenshot.png
      requestBody:
        required: true
        content:
          '*/*':
            schema:
              type: string
              format: binary
            examples:
              UploadattachmentbinaryRequestExample:
                summary: Default uploadAttachmentBinary request
                x-microcks-default: true
                value: example_value
      responses:
        '201':
          description: File successfully uploaded and attached.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Attachment'
              examples:
                Uploadattachmentbinary201Example:
                  summary: Default uploadAttachmentBinary 201 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      file_name: example_value
                      table_name: example_value
                      table_sys_id: '500123'
                      content_type: example_value
                      size_bytes: 10
                      size_compressed: 10
                      download_link: https://www.example.com
                      image_height: 10
                      image_width: 10
                      hash: example_value
                      state: example_value
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_created_by: example_value
                      sys_updated_on: '2026-01-15T10:30:00Z'
                      sys_updated_by: example_value
        '400':
          description: Bad request. Required parameters are missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Uploadattachmentbinary400Example:
                  summary: Default uploadAttachmentBinary 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Uploadattachmentbinary401Example:
                  summary: Default uploadAttachmentBinary 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /attachment/upload:
    post:
      operationId: uploadAttachmentMultipart
      summary: Servicenow Upload a File Attachment via Multipart Form Data
      description: >-
        Uploads a file using multipart form-data encoding and attaches it to
        the specified table record. This method is suitable for web browser
        and form-based uploads.
      tags:
      - Attachments
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - table_name
              - table_sys_id
              - uploadFile
              properties:
                table_name:
                  type: string
                  description: The name of the table to which the file is attached.
                table_sys_id:
                  type: string
                  description: >-
                    The sys_id of the record to which the file is attached.
                uploadFile:
                  type: string
                  format: binary
                  description: The file to upload.
            examples:
              UploadattachmentmultipartRequestExample:
                summary: Default uploadAttachmentMultipart request
                x-microcks-default: true
                value:
                  table_name: example_value
                  table_sys_id: '500123'
                  uploadFile: example_value
      responses:
        '201':
          description: File successfully uploaded and attached.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Attachment'
              examples:
                Uploadattachmentmultipart201Example:
                  summary: Default uploadAttachmentMultipart 201 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      file_name: example_value
                      table_name: example_value
                      table_sys_id: '500123'
                      content_type: example_value
                      size_bytes: 10
                      size_compressed: 10
                      download_link: https://www.example.com
                      image_height: 10
                      image_width: 10
                      hash: example_value
                      state: example_value
                      sys_created_on: '2026-01-15T10:30:00Z'
                      sys_created_by: example_value
                      sys_updated_on: '2026-01-15T10:30:00Z'
                      sys_updated_by: example_value
        '400':
          description: Bad request. Required fields are missing from the form.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Uploadattachmentmultipart400Example:
                  summary: Default uploadAttachmentMultipart 400 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Uploadattachmentmultipart401Example:
                  summary: Default uploadAttachmentMultipart 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Basic authentication with ServiceNow credentials. The user must have
        appropriate attachment permissions.
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication using ServiceNow's OAuth provider.
      flows:
        password:
          tokenUrl: https://{instance}.service-now.com/oauth_token.do
          scopes: {}
  parameters:
    sysId:
      name: sys_id
      in: path
      required: true
      description: The unique system identifier for the attachment record.
      schema:
        type: string
        pattern: '^[a-f0-9]{32}$'
  schemas:
    Attachment:
      type: object
      description: Metadata about a file attachment stored in ServiceNow.
      properties:
        sys_id:
          type: string
          description: Unique identifier for the attachment record.
          example: '500123'
        file_name:
          type: string
          description: The name of the attached file.
          example: example_value
        table_name:
          type: string
          description: The table to which the attachment belongs.
          example: example_value
        table_sys_id:
          type: string
          description: The sys_id of the record to which the file is attached.
          example: '500123'
        content_type:
          type: string
          description: The MIME type of the attached file.
          example: example_value
        size_bytes:
          type: integer
          description: The size of the attached file in bytes.
          example: 10
        size_compressed:
          type: integer
          description: The compressed size of the attached file in bytes.
          example: 10
        download_link:
          type: string
          format: uri
          description: The URL to download the attachment file content.
          example: https://www.example.com
        image_height:
          type: integer
          description: The height in pixels if the attachment is an image.
          example: 10
        image_width:
          type: integer
          description: The width in pixels if the attachment is an image.
          example: 10
        hash:
          type: string
          description: The MD5 hash of the file content.
          example: example_value
        state:
          type: string
          description: The state of the attachment processing.
          example: example_value
        sys_created_on:
          type: string
          format: date-time
          description: The date and time the attachment was created.
          example: '2026-01-15T10:30:00Z'
        sys_created_by:
          type: string
          description: The user who uploaded the attachment.
          example: example_value
        sys_updated_on:
          type: string
          format: date-time
          description: The date and time the attachment was last modified.
          example: '2026-01-15T10:30:00Z'
        sys_updated_by:
          type: string
          description: The user who last modified the attachment record.
          example: example_value
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: A human-readable error message.
            detail:
              type: string
              description: Detailed information about the error.
          example: example_value