Salesforce REST API

openapi: 3.1.0
info:
  title: Salesforce Experience Cloud Salesforce REST API
  description: >-
    Core REST API for accessing Salesforce objects and data. Provides CRUD
    operations on standard and custom objects, query execution via SOQL,
    search via SOSL, and metadata access used as the foundation for
    Experience Cloud data integrations.
  version: 59.0.0
  contact:
    name: Salesforce Developer Support
    url: https://developer.salesforce.com/
  license:
    name: Salesforce Master Subscription Agreement
    url: https://www.salesforce.com/company/legal/sfdc-website-terms-of-service/
servers:
  - url: https://{instance}.salesforce.com/services/data/v59.0
    description: Salesforce Instance
    variables:
      instance:
        default: yourInstance
        description: Your Salesforce instance name or custom domain
security:
  - oauth2: []
  - bearerAuth: []
tags:
  - name: Describe
    description: Object and field metadata
  - name: Limits
    description: API usage limits and quotas
  - name: Query
    description: SOQL query execution
  - name: Resources
    description: Available REST resources
  - name: Search
    description: SOSL search execution
  - name: sObjects
    description: Salesforce object operations
  - name: Versions
    description: API version discovery
paths:
  /services/data:
    get:
      operationId: listApiVersions
      summary: Salesforce Experience Cloud List Available API Versions
      description: >-
        Returns a list of all available REST API versions, including the
        version number, label, and a link to each version's root resource.
        This endpoint does not require authentication.
      tags:
        - Versions
      security: []
      responses:
        '200':
          description: Successfully retrieved API versions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiVersion'
  /:
    get:
      operationId: listResources
      summary: Salesforce Experience Cloud List Available Resources
      description: >-
        Returns a list of resources available for the specified API version,
        providing the name and URI of each resource. Useful for discovering
        available endpoints.
      tags:
        - Resources
      responses:
        '200':
          description: Successfully retrieved available resources
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                  format: uri
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sobjects:
    get:
      operationId: describeGlobal
      summary: Salesforce Experience Cloud Describe Global
      description: >-
        Returns a list of all sObjects available in the org, including
        metadata about each object such as label, name, key prefix,
        and available operations (createable, queryable, etc.).
      tags:
        - Describe
      parameters:
        - name: If-Modified-Since
          in: header
          description: Return objects modified since this date
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Successfully retrieved global describe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescribeGlobalResult'
        '304':
          description: No objects modified since the specified date
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sobjects/{sObjectName}:
    get:
      operationId: getSObjectBasicInfo
      summary: Salesforce Experience Cloud Get sObject Basic Information
      description: >-
        Returns metadata about the specified sObject, including the object
        describe result and recently accessed records of that type.
      tags:
        - sObjects
      parameters:
        - $ref: '#/components/parameters/SObjectName'
      responses:
        '200':
          description: Successfully retrieved sObject basic information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SObjectBasicInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createSObjectRecord
      summary: Salesforce Experience Cloud Create an sObject Record
      description: >-
        Creates a new record for the specified sObject type. The request
        body must contain the field values for the new record.
      tags:
        - sObjects
      parameters:
        - $ref: '#/components/parameters/SObjectName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Field values for the new record
              additionalProperties: true
      responses:
        '201':
          description: Record created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sobjects/{sObjectName}/describe:
    get:
      operationId: describeSObject
      summary: Salesforce Experience Cloud Describe an sObject
      description: >-
        Returns complete metadata about the specified sObject, including
        all fields, record types, child relationships, URLs, and supported
        operations. Includes field-level details such as type, length,
        picklist values, and relationship information.
      tags:
        - Describe
      parameters:
        - $ref: '#/components/parameters/SObjectName'
        - name: If-Modified-Since
          in: header
          description: Return describe only if modified since this date
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Successfully retrieved sObject describe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescribeSObjectResult'
        '304':
          description: sObject not modified since the specified date
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /sobjects/{sObjectName}/{recordId}:
    get:
      operationId: getSObjectRecord
      summary: Salesforce Experience Cloud Get an sObject Record
      description: >-
        Returns the field values for the specified record. Use the fields
        parameter to specify which fields to return. If no fields are
        specified, all accessible fields are returned.
      tags:
        - sObjects
      parameters:
        - $ref: '#/components/parameters/SObjectName'
        - $ref: '#/components/parameters/RecordId'
        - name: fields
          in: query
          description: Comma-separated list of field names to return
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved the record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SObjectRecord'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateSObjectRecord
      summary: Salesforce Experience Cloud Update an sObject Record
      description: >-
        Updates the specified record with the provided field values.
        Only fields included in the request body are updated.
      tags:
        - sObjects
      parameters:
        - $ref: '#/components/parameters/SObjectName'
        - $ref: '#/components/parameters/RecordId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Field values to update
              additionalProperties: true
      responses:
        '204':
          description: Record updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteSObjectRecord
      summary: Salesforce Experience Cloud Delete an sObject Record
      description: >-
        Deletes the specified record. The record is moved to the Recycle
        Bin unless permanently deleted.
      tags:
        - sObjects
      parameters:
        - $ref: '#/components/parameters/SObjectName'
        - $ref: '#/components/parameters/RecordId'
      responses:
        '204':
          description: Record deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /query:
    get:
      operationId: executeQuery
      summary: Salesforce Experience Cloud Execute a SOQL Query
      description: >-
        Executes a SOQL query and returns the matching records. Supports
        standard SOQL syntax including SELECT, FROM, WHERE, ORDER BY,
        LIMIT, and OFFSET clauses. Returns paginated results with a
        nextRecordsUrl for large result sets.
      tags:
        - Query
      parameters:
        - name: q
          in: query
          required: true
          description: The SOQL query string to execute
          schema:
            type: string
          example: SELECT Id, Name FROM Account LIMIT 10
      responses:
        '200':
          description: Successfully executed query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        '400':
          description: Invalid SOQL query syntax
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /queryAll:
    get:
      operationId: executeQueryAll
      summary: Salesforce Experience Cloud Execute a SOQL Query Including Deleted Records
      description: >-
        Executes a SOQL query and returns matching records including
        deleted and archived records. Otherwise behaves identically to
        the standard query endpoint.
      tags:
        - Query
      parameters:
        - name: q
          in: query
          required: true
          description: The SOQL query string to execute
          schema:
            type: string
      responses:
        '200':
          description: Successfully executed query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        '400':
          description: Invalid SOQL query syntax
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /query/{queryLocator}:
    get:
      operationId: getNextQueryPage
      summary: Salesforce Experience Cloud Get Next Page of Query Results
      description: >-
        Retrieves the next page of results for a previously executed SOQL
        query using the query locator from the nextRecordsUrl.
      tags:
        - Query
      parameters:
        - name: queryLocator
          in: path
          required: true
          description: Query locator from the previous query result
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved next page of results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /search:
    get:
      operationId: executeSearch
      summary: Salesforce Experience Cloud Execute a SOSL Search
      description: >-
        Executes a SOSL search query and returns matching records across
        multiple objects. SOSL supports full-text search with wildcard
        and phrase matching.
      tags:
        - Search
      parameters:
        - name: q
          in: query
          required: true
          description: The SOSL search string to execute
          schema:
            type: string
          example: FIND {test} IN ALL FIELDS RETURNING Account(Id, Name)
      responses:
        '200':
          description: Successfully executed search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
        '400':
          description: Invalid SOSL query syntax
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /limits:
    get:
      operationId: getLimits
      summary: Salesforce Experience Cloud Get Org Limits
      description: >-
        Returns the current API usage limits for the org, including daily
        API request limits, data storage, file storage, and other
        governor limits. Useful for monitoring API consumption.
      tags:
        - Limits
      responses:
        '200':
          description: Successfully retrieved org limits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgLimits'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: Salesforce OAuth 2.0 authentication
      flows:
        authorizationCode:
          authorizationUrl: https://login.salesforce.com/services/oauth2/authorize
          tokenUrl: https://login.salesforce.com/services/oauth2/token
          scopes:
            api: Access and manage your data
            full: Full access
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth2
      description: Bearer token obtained through OAuth 2.0 flow
  parameters:
    SObjectName:
      name: sObjectName
      in: path
      required: true
      description: The API name of the Salesforce object (e.g., Account, Contact)
      schema:
        type: string
    RecordId:
      name: recordId
      in: path
      required: true
      description: The 15 or 18 character Salesforce record ID
      schema:
        type: string
  schemas:
    ApiVersion:
      type: object
      description: Information about an available API version
      properties:
        label:
          type: string
          description: Human-readable version label
        url:
          type: string
          format: uri
          description: URL to the version's root resource
        version:
          type: string
          description: Version number (e.g., 59.0)
    DescribeGlobalResult:
      type: object
      description: Result of a global describe call
      properties:
        encoding:
          type: string
        maxBatchSize:
          type: integer
        sobjects:
          type: array
          items:
            $ref: '#/components/schemas/SObjectDescribeBrief'
    SObjectDescribeBrief:
      type: object
      description: Brief description of an sObject from global describe
      properties:
        activateable:
          type: boolean
        createable:
          type: boolean
        custom:
          type: boolean
        customSetting:
          type: boolean
        deepCloneable:
          type: boolean
        deletable:
          type: boolean
        deprecatedAndHidden:
          type: boolean
        feedEnabled:
          type: boolean
        hasSubtypes:
          type: boolean
        isInterface:
          type: boolean
        isSubtype:
          type: boolean
        keyPrefix:
          type: string
        label:
          type: string
        labelPlural:
          type: string
        layoutable:
          type: boolean
        mergeable:
          type: boolean
        mruEnabled:
          type: boolean
        name:
          type: string
        queryable:
          type: boolean
        replicateable:
          type: boolean
        retrieveable:
          type: boolean
        searchable:
          type: boolean
        triggerable:
          type: boolean
        undeletable:
          type: boolean
        updateable:
          type: boolean
        urls:
          type: object
          additionalProperties:
            type: string
    SObjectBasicInfo:
      type: object
      description: Basic information about an sObject
      properties:
        objectDescribe:
          $ref: '#/components/schemas/SObjectDescribeBrief'
        recentItems:
          type: array
          items:
            $ref: '#/components/schemas/SObjectRecord'
    DescribeSObjectResult:
      type: object
      description: Complete describe result for an sObject
      properties:
        actionOverrides:
          type: array
          items:
            type: object
        activateable:
          type: boolean
        childRelationships:
          type: array
          items:
            $ref: '#/components/schemas/ChildRelationship'
        compactLayoutable:
          type: boolean
        createable:
          type: boolean
        custom:
          type: boolean
        customSetting:
          type: boolean
        deletable:
          type: boolean
        deprecatedAndHidden:
          type: boolean
        feedEnabled:
          type: boolean
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FieldDescribe'
        hasSubtypes:
          type: boolean
        isSubtype:
          type: boolean
        keyPrefix:
          type: string
        label:
          type: string
        labelPlural:
          type: string
        layoutable:
          type: boolean
        listviewable:
          type: boolean
        lookupLayoutable:
          type: boolean
        mergeable:
          type: boolean
        mruEnabled:
          type: boolean
        name:
          type: string
        namedLayoutInfos:
          type: array
          items:
            type: object
        networkScopeFieldName:
          type: string
        queryable:
          type: boolean
        recordTypeInfos:
          type: array
          items:
            $ref: '#/components/schemas/RecordTypeInfo'
        replicateable:
          type: boolean
        retrieveable:
          type: boolean
        searchLayoutable:
          type: boolean
        searchable:
          type: boolean
        supportedScopes:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
              name:
                type: string
        triggerable:
          type: boolean
        undeletable:
          type: boolean
        updateable:
          type: boolean
        urls:
          type: object
          additionalProperties:
            type: string
    FieldDescribe:
      type: object
      description: Metadata about a field
      properties:
        aggregatable:
          type: boolean
        aiPredictionField:
          type: boolean
        autoNumber:
          type: boolean
        byteLength:
          type: integer
        calculated:
          type: boolean
        calculatedFormula:
          type: string
        cascadeDelete:
          type: boolean
        caseSensitive:
          type: boolean
        compoundFieldName:
          type: string
        controllerName:
          type: string
        createable:
          type: boolean
        custom:
          type: boolean
        defaultValue:
          type: string
        defaultValueFormula:
          type: string
        defaultedOnCreate:
          type: boolean
        dependentPicklist:
          type: boolean
        deprecatedAndHidden:
          type: boolean
        digits:
          type: integer
        displayLocationInDecimal:
          type: boolean
        encrypted:
          type: boolean
        externalId:
          type: boolean
        extraTypeInfo:
          type: string
        filterable:
          type: boolean
        filteredLookupInfo:
          type: object
        formulaTreatNullNumberAsZero:
          type: boolean
        groupable:
          type: boolean
        highScaleNumber:
          type: boolean
        htmlFormatted:
          type: boolean
        idLookup:
          type: boolean
        inlineHelpText:
          type: string
        label:
          type: string
        length:
          type: integer
        mask:
          type: string
        maskType:
          type: string
        name:
          type: string
        nameField:
          type: boolean
        namePointing:
          type: boolean
        nillable:
          type: boolean
        permissionable:
          type: boolean
        picklistValues:
          type: array
          items:
            type: object
            properties:
              active:
                type: boolean
              defaultValue:
                type: boolean
              label:
                type: string
              validFor:
                type: string
              value:
                type: string
        polymorphicForeignKey:
          type: boolean
        precision:
          type: integer
        queryByDistance:
          type: boolean
        referenceTargetField:
          type: string
        referenceTo:
          type: array
          items:
            type: string
        relationshipName:
          type: string
        relationshipOrder:
          type: integer
        restrictedDelete:
          type: boolean
        restrictedPicklist:
          type: boolean
        scale:
          type: integer
        searchPrefilterable:
          type: boolean
        soapType:
          type: string
        sortable:
          type: boolean
        type:
          type: string
          enum:
            - id
            - boolean
            - currency
            - date
            - datetime
            - double
            - email
            - encryptedstring
            - int
            - long
            - multipicklist
            - percent
            - phone
            - picklist
            - reference
            - string
            - textarea
            - time
            - url
        unique:
          type: boolean
        updateable:
          type: boolean
        writeRequiresMasterRead:
          type: boolean
    ChildRelationship:
      type: object
      description: Describes a child relationship
      properties:
        cascadeDelete:
          type: boolean
        childSObject:
          type: string
        deprecatedAndHidden:
          type: boolean
        field:
          type: string
        junctionIdListNames:
          type: array
          items:
            type: string
        junctionReferenceTo:
          type: array
          items:
            type: string
        relationshipName:
          type: string
        restrictedDelete:
          type: boolean
    RecordTypeInfo:
      type: object
      description: Record type information
      properties:
        active:
          type: boolean
        available:
          type: boolean
        defaultRecordTypeMapping:
          type: boolean
        developerName:
          type: string
        master:
          type: boolean
        name:
          type: string
        recordTypeId:
          type: string
        urls:
          type: object
          additionalProperties:
            type: string
    SObjectRecord:
      type: object
      description: A Salesforce sObject record with field values
      properties:
        attributes:
          type: object
          properties:
            type:
              type: string
              description: sObject type name
            url:
              type: string
              format: uri
              description: REST API URL for this record
        Id:
          type: string
          description: The 18-character record ID
      additionalProperties: true
    CreateResult:
      type: object
      description: Result of a record creation
      properties:
        id:
          type: string
          description: ID of the created record
        success:
          type: boolean
          description: Whether the creation was successful
        errors:
          type: array
          description: Errors encountered during creation
          items:
            $ref: '#/components/schemas/ErrorResponse'
    QueryResult:
      type: object
      description: Result of a SOQL query
      properties:
        done:
          type: boolean
          description: Whether all results have been returned
        nextRecordsUrl:
          type: string
          format: uri
          description: URL for the next page of results (if done is false)
        records:
          type: array
          description: Matching records
          items:
            $ref: '#/components/schemas/SObjectRecord'
        totalSize:
          type: integer
          description: Total number of matching records
    SearchResult:
      type: object
      description: Result of a SOSL search
      properties:
        searchRecords:
          type: array
          description: Matching records from the search
          items:
            $ref: '#/components/schemas/SObjectRecord'
    OrgLimits:
      type: object
      description: Organization API limits
      additionalProperties:
        type: object
        properties:
          Max:
            type: integer
            description: Maximum allowed value
          Remaining:
            type: integer
            description: Remaining allowance
    ErrorResponse:
      type: object
      description: Standard Salesforce API error response
      properties:
        errorCode:
          type: string
          description: Salesforce error code
        fields:
          type: array
          items:
            type: string
        message:
          type: string
          description: Human-readable error message
  responses:
    BadRequest:
      description: Bad request - invalid input parameters
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - invalid or expired OAuth token
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ErrorResponse'