---
openapi: 3.0.3
info:
  title: "Braze REST API \u2013 Replace object relationship"
  description: |
    ## Prerequisites

    To use this endpoint, you need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with `data_objects.object_relationships.update`.

    ## Rate limit

    This endpoint is in the Data Objects write bucket with a default limit of 1000 requests per minute.
  version: 1.0.0
  contact:
    name: Braze Support
    url: https://www.braze.com/docs/braze_support/
  license:
    name: Braze Documentation
    url: https://www.braze.com/docs/api/home/
servers:
- url: https://rest.iad-01.braze.com
  description: US-01
- url: https://rest.iad-02.braze.com
  description: US-02
- url: https://rest.iad-03.braze.com
  description: US-03
- url: https://rest.iad-04.braze.com
  description: US-04
- url: https://rest.iad-05.braze.com
  description: US-05
- url: https://rest.iad-06.braze.com
  description: US-06
- url: https://rest.iad-07.braze.com
  description: US-07
- url: https://rest.iad-08.braze.com
  description: US-08
- url: https://rest.us-10.braze.com
  description: US-10
- url: https://rest.fra-01.braze.eu
  description: EU-01
- url: https://rest.fra-02.braze.eu
  description: EU-02
- url: https://rest.au-01.braze.com
  description: AU-01
- url: https://rest.id-01.braze.com
  description: ID-01
- url: https://rest.jp-01.braze.com
  description: JP-01
- url: https://rest.kr-01.braze.com
  description: KR-01
security:
- BearerAuth: []
paths:
  /data_objects/objects/{type_name}/{object_id}/object_relationships:
    put:
      summary: Replace object relationship
      operationId: put_data_objects_objects_type_name_object_id_object_relationships_put_replace_object_relationship
      parameters:
        - name: type_name
          in: path
          required: true
          description: URL object type
          schema:
            type: string
          example: account
        - name: object_id
          in: path
          required: true
          description: URL object identifier
          schema:
            type: string
          example: acct-123
      requestBody:
        required: true
        description: This section includes a sample JSON payload and a sample cURL request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplaceObjectRelationshipRequest'
            examples:
              replace_subaccount:
                summary: Replace a subaccount relationship
                description: This example replaces the `subaccount` relationship between `acct-123` and `acct-456`, overwriting any attributes previously stored on it.
                value:
                  rel_kind: subaccount
                  related_type_name: account
                  related_object_id: acct-456
                  attributes: {}
      responses:
        "200":
          description: |
            The request succeeded and the relationship was created or replaced. This section includes a sample successful response and the response fields.

            The status code `200` could return the following response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectRelationshipResponse'
              examples:
                success:
                  summary: Relationship created or replaced
                  value:
                    object_relationship:
                      rel_kind: subaccount
                      to_data_object:
                        type_name: account
                        object_id: acct-456
                        attributes:
                          name: Child Account
                      attributes: {}
        "400":
          description: |
            Bad request. Validation error. Confirm `rel_kind` and `attributes` are valid for the relationship type.

            Braze also returns `400` with the `invalid_request` error code when a value or field name in the request body, path, or query isn't valid UTF-8 or contains the null character. The error names each affected field in `source` and doesn't include the value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unknown_rel_kind:
                  summary: Unknown relationship kind
                  value:
                    error: Object relationship type 'subaccount' not found.
                related_type_mismatch:
                  summary: Related type doesn't match the relationship kind
                  value:
                    error: Related data object type does not match relationship type 'subaccount'.
                invalid_characters:
                  summary: Value isn't valid UTF-8
                  value:
                    errors:
                      - id: 3f0c7a52-9b1e-4d6a-8c2f-5e7b1a9d4c60
                        status_code: 400
                        error_code: invalid_request
                        message: object_id must be valid UTF-8
                        source:
                          path: object_id
                date_only_value:
                  summary: Date field without a time and time zone
                  value:
                    error: "Validation failed: Attrs do not conform to field definitions: The property '#/start_date' must be a valid RFC3339 date/time string"
        "401":
          description: Unauthorized. Missing or invalid REST API key. The REST API key is missing, malformed, or sent to the wrong REST endpoint. Verify the `Authorization` header uses `Bearer YOUR_REST_API_KEY` and that the key is active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_api_key:
                  summary: Missing or invalid API key
                  value:
                    error: Error authenticating credentials
        "403":
          description: Access denied. API key lacks permission or request is blocked by allowlist. Confirm the key has `data_objects.object_relationships.update` and that your source IP is on the key allowlist, if configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                access_denied:
                  summary: Missing permission
                  value:
                    error: You do not have permission to access this resource
                ip_not_allowed:
                  summary: Source IP not on the key allowlist
                  value:
                    error: IP address 203.0.113.10 is not whitelisted
        "404":
          description: Not found. Relationship or endpoint objects not found (`data-object-relationship-not-found`). Confirm both objects and related type names exist in the workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                relationship_not_found:
                  summary: Relationship not found
                  value:
                    errors:
                      - id: data-object-relationship-not-found
                        message: Data object relationship not found.
                object_not_found:
                  summary: Related object not found
                  value:
                    errors:
                      - id: data-object-not-found
                        message: Data object not found.
                        parameters:
                          - related_type_name
                          - related_object_id
                        parameter_values:
                          - account
                          - acct-456
        "409":
          description: Conflict. Cardinality conflict (`data-object-parent-conflict`). The relationship type allows only one link on one side, and that object already has one. Delete the existing link before creating the new one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                parent_conflict:
                  summary: Relationship type allows only one link on that side
                  value:
                    errors:
                      - id: data-object-parent-conflict
                        message: This relationship allows only one link on that side
        "422":
          description: Unprocessable entity. Per-object relationship limit reached (`data-object-relationship-limit-exceeded`). Reduce relationship count for the object, or contact Braze support about workspace limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "429":
          description: Too many requests. Rate limit exceeded. Retry after `X-RateLimit-Reset` and reduce request frequency.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                over_rate_limit:
                  summary: Over rate limit
                  value:
                    errors:
                      - id: rate-limit-exceeded
                        message: You have exceeded your limit of 1000 requests per minute. Please contact your account executive to increase your limit. If you do not have their info, you may contact Braze directly at https://www.braze.com/contact/.
        5XX:
          description: |
            Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: REST API key
      description: |
        REST API keys are created in the Braze dashboard at **Settings → APIs and
        Identifiers → API Keys**. The key must include the `data_objects.object_relationships.update` permission.
        Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`.
  schemas:
    ReplaceObjectRelationshipRequest:
      title: Replace object relationship request
      type: object
      required: [rel_kind, related_type_name, related_object_id]
      properties:
        rel_kind:
          type: string
          description: Relationship kind
          example: subaccount
        related_type_name:
          type: string
          description: Related object type
          example: account
        related_object_id:
          type: string
          description: Related object identifier
          example: acct-456
        attributes:
          type: object
          additionalProperties: true
          description: 'Relationship attributes. Date fields must be RFC 3339 date-time strings that include a time and time zone, such as `2026-11-03T00:00:00Z`. Braze rejects date-only values such as `2026-11-03` with a `400` error. For details, see [Date field format]({{site.baseurl}}/api/endpoints/data_objects#date-field-format).'
          example: {}
    RelatedDataObject:
      title: Related data object
      type: object
      required: [type_name, object_id]
      properties:
        type_name:
          type: string
          description: Related object type name
          example: account
        object_id:
          type: string
          description: Related object identifier
          example: acct-456
        attributes:
          type: object
          additionalProperties: true
          description: Related object attributes. Returned only when the API key also has `data_objects.read`.
          example:
            name: Child Account
    ObjectRelationship:
      title: Object relationship
      type: object
      required: [rel_kind, attributes]
      properties:
        rel_kind:
          type: string
          description: Relationship kind value
          example: subaccount
        to_data_object:
          allOf:
            - $ref: '#/components/schemas/RelatedDataObject'
          description: Related object
        attributes:
          type: object
          additionalProperties: true
          description: Relationship attributes
          example: {}
    ObjectRelationshipResponse:
      title: Replace object relationship response
      type: object
      required: [object_relationship]
      properties:
        object_relationship:
          allOf:
            - $ref: '#/components/schemas/ObjectRelationship'
          description: Created or replaced relationship record
    ErrorDetail:
      title: Error detail
      type: object
      properties:
        id:
          type: string
          description: Error identifier, such as `data-object-relationship-not-found`.
        message:
          type: string
          description: Human-readable error message.
        parameters:
          type: array
          description: Request parameters the error applies to.
          items:
            type: string
        parameter_values:
          type: array
          description: Values sent for those parameters, in the same order.
          items:
            type: string
        status_code:
          type: integer
          description: HTTP status code. Included with `invalid_request` errors.
          example: 400
        error_code:
          type: string
          description: Error code, such as `invalid_request`. When it's present, `id` is a unique identifier for this error occurrence.
          example: invalid_request
        source:
          title: Error source
          type: object
          description: The request field the error applies to. Included with `invalid_request` errors.
          properties:
            path:
              type: string
              description: Dot-separated path to the field, such as `attributes.name`, when one field is affected.
            paths:
              type: array
              description: Dot-separated paths to each field, when more than one field is affected.
              items:
                type: string
    ErrorResponse:
      title: Error
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
        error:
          type: string
          description: Human-readable error message for authentication, permission, and argument errors.
        errors:
          type: array
          description: Optional list of detailed validation errors.
          items:
            $ref: '#/components/schemas/ErrorDetail'
