openapi: 3.2.0
info:
  title: Salesforce UI Records API
  description: The Salesforce UI API provides a comprehensive REST interface for building user interfaces that work with Salesforce metadata and data. It returns layout information, picklist values, list views, record data, and object metadata that Lightning components rely on. Unlike the general REST API, the UI API returns UI-ready data including display labels, field types, formatting hints, and page layout assignments.
  version: '59.0'
  contact:
    name: Salesforce Developer Support
    url: https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/
  termsOfService: https://www.salesforce.com/company/legal/agreements/
servers:
- url: https://{instanceName}.salesforce.com/services/data/v{version}/ui-api
  description: Salesforce org UI API base
  variables:
    instanceName:
      description: Salesforce org instance name or custom domain
      default: myorg
    version:
      description: Salesforce API version
      default: '59.0'
security:
- oauthBearerToken: []
tags:
- name: Records
  description: Retrieve record data with field labels and UI-formatting metadata
paths:
  /records/{recordId}:
    get:
      operationId: getRecord
      summary: Salesforce Get a Record
      description: Returns data for a record including field values, formatted for display in the Lightning UI. Supports specifying which fields to return using the fields or layoutTypes parameter. Returns record metadata alongside data, including field labels, editability, and required status.
      tags:
      - Records
      parameters:
      - $ref: '#/components/parameters/RecordId'
      - name: fields
        in: query
        description: Comma-separated list of field API names to return (e.g., Account.Name,Account.Type)
        schema:
          type: string
        example: example_value
      - name: layoutTypes
        in: query
        description: Layout types to use for determining which fields to return (Full, Compact)
        schema:
          type: string
          enum:
          - Full
          - Compact
        example: Full
      - name: modes
        in: query
        description: View mode(s) for the layout (View, Edit, Create)
        schema:
          type: string
        example: example_value
      - name: optionalFields
        in: query
        description: Fields to include if accessible, without error if inaccessible
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Record data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordRepresentation'
              examples:
                Getrecord200Example:
                  summary: Default getRecord 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    apiName: example_value
                    childRelationships: example_value
                    eTag: example_value
                    fields: example_value
                    recordTypeId: '500123'
                    recordTypeInfo:
                      available: true
                      defaultRecordTypeMapping: true
                      master: true
                      name: Example Title
                      recordTypeId: '500123'
                    systemModstamp: '2026-01-15T10:30:00Z'
                    lastModifiedById: '500123'
                    lastModifiedDate: '2026-01-15T10:30:00Z'
                    createdById: '500123'
                    createdDate: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateRecord
      summary: Salesforce Update a Record
      description: Updates fields on a Salesforce record. Only the fields included in the request body are updated. Returns the updated record representation.
      tags:
      - Records
      parameters:
      - $ref: '#/components/parameters/RecordId'
      - name: If-Modified-Since
        in: header
        description: Conditional update based on record modification timestamp
        schema:
          type: string
        example: example_value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordInput'
            examples:
              UpdaterecordRequestExample:
                summary: Default updateRecord request
                x-microcks-default: true
                value:
                  apiName: example_value
                  fields: example_value
      responses:
        '200':
          description: Record updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordRepresentation'
              examples:
                Updaterecord200Example:
                  summary: Default updateRecord 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    apiName: example_value
                    childRelationships: example_value
                    eTag: example_value
                    fields: example_value
                    recordTypeId: '500123'
                    recordTypeInfo:
                      available: true
                      defaultRecordTypeMapping: true
                      master: true
                      name: Example Title
                      recordTypeId: '500123'
                    systemModstamp: '2026-01-15T10:30:00Z'
                    lastModifiedById: '500123'
                    lastModifiedDate: '2026-01-15T10:30:00Z'
                    createdById: '500123'
                    createdDate: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteRecord
      summary: Salesforce Delete a Record
      description: Deletes a Salesforce record by its ID.
      tags:
      - Records
      parameters:
      - $ref: '#/components/parameters/RecordId'
      responses:
        '204':
          description: Record deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /records:
    post:
      operationId: createRecord
      summary: Salesforce Create a Record
      description: Creates a new Salesforce record of the specified object type. The apiName of the object is included in the request body.
      tags:
      - Records
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordInput'
            examples:
              CreaterecordRequestExample:
                summary: Default createRecord request
                x-microcks-default: true
                value:
                  apiName: example_value
                  fields: example_value
      responses:
        '201':
          description: Record created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordRepresentation'
              examples:
                Createrecord201Example:
                  summary: Default createRecord 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    apiName: example_value
                    childRelationships: example_value
                    eTag: example_value
                    fields: example_value
                    recordTypeId: '500123'
                    recordTypeInfo:
                      available: true
                      defaultRecordTypeMapping: true
                      master: true
                      name: Example Title
                      recordTypeId: '500123'
                    systemModstamp: '2026-01-15T10:30:00Z'
                    lastModifiedById: '500123'
                    lastModifiedDate: '2026-01-15T10:30:00Z'
                    createdById: '500123'
                    createdDate: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    RecordRepresentation:
      type: object
      description: A Salesforce record with field values and UI metadata
      properties:
        id:
          type: string
          description: The 18-character Salesforce record ID
          example: abc123
        apiName:
          type: string
          description: The API name of the object type
          example: example_value
        childRelationships:
          type: object
          description: Child relationship data indexed by relationship name
          additionalProperties: true
          example: example_value
        eTag:
          type: string
          description: ETag for optimistic concurrency control
          example: example_value
        fields:
          type: object
          description: Field values indexed by field API name
          additionalProperties:
            $ref: '#/components/schemas/FieldValueRepresentation'
          example: example_value
        recordTypeId:
          type: string
          description: The record type ID
          example: '500123'
        recordTypeInfo:
          type: object
          description: Record type metadata
          properties:
            available:
              type: boolean
            defaultRecordTypeMapping:
              type: boolean
            master:
              type: boolean
            name:
              type: string
            recordTypeId:
              type: string
          example: example_value
        systemModstamp:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        lastModifiedById:
          type: string
          example: '500123'
        lastModifiedDate:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        createdById:
          type: string
          example: '500123'
        createdDate:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
    ErrorResponse:
      type: object
      description: API error response
      properties:
        errorCode:
          type: string
          description: Machine-readable error code
          example: example_value
        message:
          type: string
          description: Human-readable error message
          example: example_value
    FieldValueRepresentation:
      type: object
      description: A field value with display metadata
      properties:
        displayValue:
          description: Human-readable formatted display value (for dates, picklists, lookups)
          nullable: true
          oneOf:
          - type: string
          - type: 'null'
          example: example_value
        value:
          description: Raw field value
          nullable: true
          example: example_value
    RecordInput:
      type: object
      description: Input for creating or updating a record
      required:
      - apiName
      - fields
      properties:
        apiName:
          type: string
          description: The API name of the object type
          example: example_value
        fields:
          type: object
          description: Field values to set, indexed by field API name
          additionalProperties:
            description: Field value (string, number, boolean, or null to clear)
          example: example_value
  responses:
    NotFound:
      description: Not found. The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request. Invalid parameters or request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden. Insufficient permissions for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized. Session has expired or is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    RecordId:
      name: recordId
      in: path
      required: true
      description: The 18-character Salesforce record ID
      schema:
        type: string
        pattern: ^[a-zA-Z0-9]{18}$
  securitySchemes:
    oauthBearerToken:
      type: http
      scheme: bearer
      description: Salesforce OAuth 2.0 Bearer Token
externalDocs:
  description: Salesforce UI API Documentation
  url: https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/