openapi: 3.1.0
info:
  title: ServiceNow Table API
  description: >-
    The ServiceNow Table API provides endpoints to perform create, read, update,
    and delete (CRUD) operations on records within any ServiceNow table. It is
    the primary REST interface for interacting with ServiceNow platform data
    such as incidents, problems, changes, and custom tables. All operations
    support query filtering, field selection, pagination, and display value
    control.
  version: 'Yokohama'
  contact:
    name: ServiceNow Support
    url: https://support.servicenow.com
  termsOfService: https://www.servicenow.com/terms-of-use.html
externalDocs:
  description: ServiceNow Table API Documentation
  url: https://www.servicenow.com/docs/bundle/yokohama-api-reference/page/integrate/inbound-rest/concept/c_TableAPI.html
servers:
- url: https://{instance}.service-now.com/api/now
  description: ServiceNow Instance
  variables:
    instance:
      default: instance
      description: Your ServiceNow instance name
tags:
- name: Table Records
  description: >-
    Operations for creating, reading, updating, and deleting records in
    ServiceNow tables.
security:
- basicAuth: []
- oauth2: []
paths:
  /table/{tableName}:
    get:
      operationId: listRecords
      summary: Servicenow List Records From a Table
      description: >-
        Retrieves multiple records from the specified ServiceNow table. Supports
        encoded query filtering, field selection, pagination via limit and
        offset, and control over display values and link formatting.
      tags:
      - Table Records
      parameters:
      - $ref: '#/components/parameters/tableName'
      - $ref: '#/components/parameters/sysparmQuery'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmLimit'
      - $ref: '#/components/parameters/sysparmOffset'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      - $ref: '#/components/parameters/sysparmExcludeReferenceLink'
      - $ref: '#/components/parameters/sysparmSuppressPaginationHeader'
      - $ref: '#/components/parameters/sysparmView'
      - $ref: '#/components/parameters/sysparmQueryCategory'
      - $ref: '#/components/parameters/sysparmQueryNoDomain'
      - $ref: '#/components/parameters/sysparmNoCount'
      responses:
        '200':
          description: >-
            Successful response returning an array of records matching the query
            criteria.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Record'
              examples:
                Listrecords200Example:
                  summary: Default listRecords 200 response
                  x-microcks-default: true
                  value:
                    result:
                    - sys_id: '500123'
                      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
                      sys_mod_count: 42
                      sys_tags: example_value
                      sys_class_name: example_value
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listrecords401Example:
                  summary: Default listRecords 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '403':
          description: >-
            Forbidden. The authenticated user does not have access to the
            specified table.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Listrecords403Example:
                  summary: Default listRecords 403 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createRecord
      summary: Servicenow Create a Record in a Table
      description: >-
        Creates a new record in the specified ServiceNow table. The request body
        should contain field name-value pairs for the new record. Fields not
        included in the request body use their default values.
      tags:
      - Table Records
      parameters:
      - $ref: '#/components/parameters/tableName'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      - $ref: '#/components/parameters/sysparmExcludeReferenceLink'
      - $ref: '#/components/parameters/sysparmView'
      - $ref: '#/components/parameters/sysparmInputDisplayValue'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordInput'
            examples:
              CreaterecordRequestExample:
                summary: Default createRecord request
                x-microcks-default: true
                value: {}
      responses:
        '201':
          description: Record successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Record'
              examples:
                Createrecord201Example:
                  summary: Default createRecord 201 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      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
                      sys_mod_count: 42
                      sys_tags: example_value
                      sys_class_name: example_value
        '400':
          description: Bad request. The request body contains invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Createrecord400Example:
                  summary: Default createRecord 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:
                Createrecord401Example:
                  summary: Default createRecord 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /table/{tableName}/{sys_id}:
    get:
      operationId: getRecord
      summary: Servicenow Retrieve a Single Record
      description: >-
        Retrieves a single record from the specified table by its unique sys_id
        identifier. Supports field selection and display value formatting.
      tags:
      - Table Records
      parameters:
      - $ref: '#/components/parameters/tableName'
      - $ref: '#/components/parameters/sysId'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      - $ref: '#/components/parameters/sysparmExcludeReferenceLink'
      - $ref: '#/components/parameters/sysparmView'
      responses:
        '200':
          description: Successful response returning the requested record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Record'
              examples:
                Getrecord200Example:
                  summary: Default getRecord 200 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      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
                      sys_mod_count: 42
                      sys_tags: example_value
                      sys_class_name: example_value
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getrecord401Example:
                  summary: Default getRecord 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: >-
            Not found. The specified record does not exist or the user does not
            have access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Getrecord404Example:
                  summary: Default getRecord 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateRecord
      summary: Servicenow Update a Record
      description: >-
        Updates an existing record in the specified table. The request body
        should contain the fields to be updated. Fields not included in the
        request body are not modified.
      tags:
      - Table Records
      parameters:
      - $ref: '#/components/parameters/tableName'
      - $ref: '#/components/parameters/sysId'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      - $ref: '#/components/parameters/sysparmExcludeReferenceLink'
      - $ref: '#/components/parameters/sysparmView'
      - $ref: '#/components/parameters/sysparmInputDisplayValue'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordInput'
            examples:
              UpdaterecordRequestExample:
                summary: Default updateRecord request
                x-microcks-default: true
                value: {}
      responses:
        '200':
          description: Record successfully updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Record'
              examples:
                Updaterecord200Example:
                  summary: Default updateRecord 200 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      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
                      sys_mod_count: 42
                      sys_tags: example_value
                      sys_class_name: example_value
        '400':
          description: Bad request. The request body contains invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updaterecord400Example:
                  summary: Default updateRecord 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:
                Updaterecord401Example:
                  summary: Default updateRecord 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Not found. The specified record does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Updaterecord404Example:
                  summary: Default updateRecord 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: patchRecord
      summary: Servicenow Patch a Record
      description: >-
        Partially updates an existing record in the specified table. Only the
        fields included in the request body are modified. This is functionally
        similar to PUT but follows the PATCH semantics for partial updates.
      tags:
      - Table Records
      parameters:
      - $ref: '#/components/parameters/tableName'
      - $ref: '#/components/parameters/sysId'
      - $ref: '#/components/parameters/sysparmFields'
      - $ref: '#/components/parameters/sysparmDisplayValue'
      - $ref: '#/components/parameters/sysparmExcludeReferenceLink'
      - $ref: '#/components/parameters/sysparmView'
      - $ref: '#/components/parameters/sysparmInputDisplayValue'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordInput'
            examples:
              PatchrecordRequestExample:
                summary: Default patchRecord request
                x-microcks-default: true
                value: {}
      responses:
        '200':
          description: Record successfully patched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/Record'
              examples:
                Patchrecord200Example:
                  summary: Default patchRecord 200 response
                  x-microcks-default: true
                  value:
                    result:
                      sys_id: '500123'
                      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
                      sys_mod_count: 42
                      sys_tags: example_value
                      sys_class_name: example_value
        '400':
          description: Bad request. The request body contains invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Patchrecord400Example:
                  summary: Default patchRecord 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:
                Patchrecord401Example:
                  summary: Default patchRecord 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Not found. The specified record does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Patchrecord404Example:
                  summary: Default patchRecord 404 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteRecord
      summary: Servicenow Delete a Record
      description: >-
        Deletes a record from the specified table by its sys_id. This operation
        is permanent and cannot be undone through the API.
      tags:
      - Table Records
      parameters:
      - $ref: '#/components/parameters/tableName'
      - $ref: '#/components/parameters/sysId'
      responses:
        '204':
          description: Record successfully deleted. No content returned.
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Deleterecord401Example:
                  summary: Default deleteRecord 401 response
                  x-microcks-default: true
                  value:
                    error:
                      message: example_value
                      detail: example_value
        '404':
          description: Not found. The specified record does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Deleterecord404Example:
                  summary: Default deleteRecord 404 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
        the rest_service role or appropriate table-level ACL permissions.
    oauth2:
      type: oauth2
      description: >-
        OAuth 2.0 authentication using ServiceNow's OAuth provider. Requires
        a registered OAuth application on the instance.
      flows:
        authorizationCode:
          authorizationUrl: https://{instance}.service-now.com/oauth_auth.do
          tokenUrl: https://{instance}.service-now.com/oauth_token.do
          scopes: {}
        password:
          tokenUrl: https://{instance}.service-now.com/oauth_token.do
          scopes: {}
  parameters:
    tableName:
      name: tableName
      in: path
      required: true
      description: >-
        The name of the ServiceNow table to operate on, such as incident,
        change_request, cmdb_ci, or any custom table.
      schema:
        type: string
      example: incident
    sysId:
      name: sys_id
      in: path
      required: true
      description: >-
        The unique 32-character system identifier for a record in ServiceNow.
      schema:
        type: string
        pattern: '^[a-f0-9]{32}$'
    sysparmQuery:
      name: sysparm_query
      in: query
      required: false
      description: >-
        An encoded query string used to filter the result set. Supports
        operators like =, !=, LIKE, STARTSWITH, ENDSWITH, IN, and boolean
        operators ^, ^OR. Use ORDERBY and ORDERBYDESC for sorting.
      schema:
        type: string
      example: 'active=true^priority=1^ORDERBYDESCsys_created_on'
    sysparmFields:
      name: sysparm_fields
      in: query
      required: false
      description: >-
        A comma-separated list of field names to include in the response.
        When specified, only these fields are returned, improving response
        performance.
      schema:
        type: string
      example: 'sys_id,number,short_description,state,priority'
    sysparmLimit:
      name: sysparm_limit
      in: query
      required: false
      description: >-
        The maximum number of records to return in a single request. The
        default is determined by the instance configuration, typically 10000.
      schema:
        type: integer
        minimum: 1
        default: 10000
    sysparmOffset:
      name: sysparm_offset
      in: query
      required: false
      description: >-
        The starting record index for pagination. Use with sysparm_limit to
        page through large result sets.
      schema:
        type: integer
        minimum: 0
        default: 0
    sysparmDisplayValue:
      name: sysparm_display_value
      in: query
      required: false
      description: >-
        Controls the format of field values in the response. Set to true to
        return display values, false to return actual values, or all to return
        both in a display_value and value object.
      schema:
        type: string
        enum:
        - 'true'
        - 'false'
        - all
        default: 'false'
    sysparmExcludeReferenceLink:
      name: sysparm_exclude_reference_link
      in: query
      required: false
      description: >-
        When set to true, reference fields do not include a link attribute in
        the response, reducing payload size.
      schema:
        type: boolean
        default: false
    sysparmSuppressPaginationHeader:
      name: sysparm_suppress_pagination_header
      in: query
      required: false
      description: >-
        When set to true, the Link header for pagination is not included in
        the response.
      schema:
        type: boolean
        default: false
    sysparmView:
      name: sysparm_view
      in: query
      required: false
      description: >-
        The UI view to use for determining which fields to return. When
        specified, only fields visible in the named view are included.
      schema:
        type: string
    sysparmInputDisplayValue:
      name: sysparm_input_display_value
      in: query
      required: false
      description: >-
        When set to true, input values are treated as display values rather
        than actual values. This allows setting fields using their display
        labels instead of internal values.
      schema:
        type: boolean
        default: false
    sysparmQueryCategory:
      name: sysparm_query_category
      in: query
      required: false
      description: >-
        The name of the query category used to filter the query.
      schema:
        type: string
    sysparmQueryNoDomain:
      name: sysparm_query_no_domain
      in: query
      required: false
      description: >-
        When set to true, the query ignores domain separation and returns
        records from all domains.
      schema:
        type: boolean
        default: false
    sysparmNoCount:
      name: sysparm_no_count
      in: query
      required: false
      description: >-
        When set to true, the response does not include the X-Total-Count
        header, which can improve performance for large tables.
      schema:
        type: boolean
        default: false
  schemas:
    Record:
      type: object
      description: >-
        A generic ServiceNow record. The actual fields depend on the table
        being queried. Common system fields are included in every record.
      properties:
        sys_id:
          type: string
          description: The unique 32-character system identifier for the record.
          example: '500123'
        sys_created_on:
          type: string
          format: date-time
          description: The date and time when the record was created.
          example: '2026-01-15T10:30:00Z'
        sys_created_by:
          type: string
          description: The user who created the record.
          example: example_value
        sys_updated_on:
          type: string
          format: date-time
          description: The date and time when the record was last updated.
          example: '2026-01-15T10:30:00Z'
        sys_updated_by:
          type: string
          description: The user who last updated the record.
          example: example_value
        sys_mod_count:
          type: integer
          description: The number of times the record has been modified.
          example: 42
        sys_tags:
          type: string
          description: System tags associated with the record.
          example: example_value
        sys_class_name:
          type: string
          description: The table class name for the record.
          example: example_value
      additionalProperties: true
    RecordInput:
      type: object
      description: >-
        A set of field name-value pairs to create or update a record. The
        accepted fields depend on the target table and the user's ACL
        permissions.
      additionalProperties: true
    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