Adobe Suite Graph API

openapi: 3.2.0
info:
  title: Identity Service Graph API
  description: 'Delivering relevant digital experiences requires having a complete

    understanding of your customer.'
  version: 1.0.0
servers:
- url: https://{environment}.adobe.io/data/core
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: Graph API
  description: Graph API provides access to groupings of identities as linked in the identity graph.
paths:
  /identity/v2/graph:
    post:
      tags:
      - Graph API
      operationId: getGraphs
      summary: List linked identities
      description: Given set of identities, returns all linked identities in the graph corresponding to each identity.
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/content-type'
      requestBody:
        description: "JSON object containing the list of xids/composite_xids identities for which to retrieved \nlinked identities in the same format and additional filters. <br/><br/>\nLinked identities can be returned as a `set` or `graph` projection by setting `projection_type`.<br/><br/>\nThe `projection_type: graph` option can be used alongside `require_edge_meta_data: true` to provide\ninformation about the datasets and batches which have contributed to each edge.\n"
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/GraphRequestCompositeXids'
              - $ref: '#/components/schemas/GraphRequestXids'
            examples:
              setOfMembersWithNamespaceCodeFilter:
                summary: get a set of linked identities using the namespace code
                value:
                  composite_xids:
                  - ns: adcould
                    id: '2521328045094711779817'
                  projection_type: set
              graphOfMembersWithNamespaceIdFilter:
                summary: get a graph of linked identities using the namespace id
                value:
                  composite_xids:
                  - nsid: 411
                    id: '2521328045094711779817'
                  projection_type: graph
                  require_edge_meta_data: true
              graphOfMembersWithXids:
                summary: get a graph of linked identities using xids
                value:
                  xids:
                  - HHDAHDKYYD
                  - ABXZDAFGYY
                  projection_type: graph
                  require_edge_meta_data: true
        required: true
      responses:
        '200':
          description: OK
          x-summary: Success - Data Retrieved
          headers:
            content-type:
              description: Response is a JSON document with UTF-8 encoding
              schema:
                type: string
                default: application/json;charset=utf-8
            cache-control:
              description: caching policy for response
              schema:
                type: string
                default: no-cache
          content:
            application/json;version=2.2.1;charset=utf-8:
              schema:
                $ref: '#/components/schemas/GraphResponse'
              examples:
                setOfMembersWithNamespaceCodeFilter:
                  summary: get a set of linked identities using the namespace code
                  value:
                    version: '2.0'
                    graphs:
                    - composite_xid:
                        ns: adcloud
                        id: '2521328045094711779817'
                      members:
                      - ns: adcloud
                        id: '2521328045094711779817'
                      - ns: ECID
                        id: '1111111111111'
                      - ns: Email
                        id: janeDoe@adobe.com
                      - ns: Email
                        id: johnDoe@adobe.com
                      - ns: Phone
                        id: 0000000009
                    unprocessed_composite_xids: []
                    algo_type: STITCH_ALL
                graphOfMembersWithNamespaceIdFilter:
                  summary: get a graph of linked identities using the namespace id
                  value:
                    version: '2.0'
                    graphs:
                    - composite_xid:
                        nsid: 411
                        id: '2521328045094711779817'
                      vertices:
                      - composite_xid:
                          nsid: 411
                          id: '2521328045094711779817'
                        last_updated_ts: 1724757940000
                      - composite_xid:
                          nsid: 4
                          id: '1111111111111'
                        last_updated_ts: 1724757940000
                      - composite_xid:
                          nsid: 6
                          id: janeDoe@adobe.com
                        last_updated_ts: 1724313364568
                      - composite_xid:
                          nsid: 6
                          id: johnDoe@adobe.com
                        last_updated_ts: 1724313364568
                      - composite_xid:
                          nsid: 7
                          id: 0000000009
                        last_updated_ts: 1724313042154
                      edges:
                      - composite_xid_pair:
                        - nsid: 411
                          id: '2521328045094711779817'
                        - nsid: 7
                          id: 0000000009
                        first_established_ts: 1724313042154
                        last_established_ts: 1724313042154
                        dataset_ids:
                        - 66b61a17dd6e6e1767a897fd
                        batch_ids:
                        - 01J5WGCRZCK5C0Y30SKPZ6KNDF
                      - composite_xid_pair:
                        - nsid: 6
                          id: janeDoe@adobe.com
                        - nsid: 6
                          id: johnDoe@adobe.com
                        first_established_ts: 1724313364568
                        last_established_ts: 1724313364568
                        dataset_ids:
                        - 66b61a17dd6e6e1767a897fd
                        batch_ids:
                        - 01J5WGCRZCK5C0Y30SKPA21687
                      - composite_xid_pair:
                        - nsid: 411
                          id: '2521328045094711779817'
                        - nsid: 6
                          id: johnDoe@adobe.com
                        first_established_ts: 1724313364568
                        last_established_ts: 1724313364568
                        dataset_ids:
                        - 66b61a17dd6e6e1767a897fd
                        batch_ids:
                        - 01J5WGCRZCK5C0Y30SKPA21687
                      - composite_xid_pair:
                        - nsid: 411
                          id: '2521328045094711779817'
                        - nsid: 4
                          id: '1111111111111'
                        first_established_ts: 1724757940000
                        last_established_ts: 1724757940000
                        dataset_ids:
                        - 66b61a17dd6e6e1767a897fd
                        batch_ids:
                        - 01J5WGCRZCK5C0Y30SKPZ6KAKD
                    unprocessed_composite_xids: []
                    algo_type: STITCH_ALL
                graphOfMembersWithXids:
                  summary: get a graph of linked identities using xids
                  value:
                    version: '2.0'
                    graphs:
                    - xid: HHDAHDKYYD
                      vertices:
                      - xid: HHDAHDKYYD
                        last_updated_ts: 1724757940000
                      - xid: HHDAHDKABD
                        last_updated_ts: 1724757940000
                      - xid: AD1JBUOPJD
                        last_updated_ts: 1724313364568
                      - xid: UGJUHGFKUG
                        last_updated_ts: 1724313364568
                      - xid: YUGVgfjgikFSFUK
                        last_updated_ts: 1724313042154
                      edges:
                      - xid_pair:
                        - HHDAHDKYYD
                        - YUGVgfjgikFSFUK
                        first_established_ts: 1724313042154
                        last_established_ts: 1724313042154
                        dataset_ids:
                        - 66b61a17dd6e6e1767a897fd
                        batch_ids:
                        - 01J5WGCRZCK5C0Y30SKPZ6KNDF
                      - xid_pair:
                        - AD1JBUOPJD
                        - UGJUHGFKUG
                        first_established_ts: 1724313364568
                        last_established_ts: 1724313364568
                        dataset_ids:
                        - 66b61a17dd6e6e1767a897fd
                        batch_ids:
                        - 01J5WGCRZCK5C0Y30SKPA21687
                      - xid_pair:
                        - HHDAHDKYYD
                        - UGJUHGFKUG
                        first_established_ts: 1724313364568
                        last_established_ts: 1724313364568
                        dataset_ids:
                        - 66b61a17dd6e6e1767a897fd
                        batch_ids:
                        - 01J5WGCRZCK5C0Y30SKPA21687
                      - xid_pair:
                        - HHDAHDKYYD
                        - HHDAHDKABD
                        first_established_ts: 1724757940000
                        last_established_ts: 1724757940000
                        dataset_ids:
                        - 66b61a17dd6e6e1767a897fd
                        batch_ids:
                        - 01J5WGCRZCK5C0Y30SKPZ6KAKD
                    - xid: ABXZDAFGYY
                      vertices:
                      - xid: ABXZDAFGYY
                        last_updated_ts: 1724757940000
                      - xid: LKGUYP588hguj
                        last_updated_ts: 1724757940000
                      - xid: BVR478768HGFJHVJK
                        last_updated_ts: 1724757940000
                      edges:
                      - xid_pair:
                        - ABXZDAFGYY
                        - LKGUYP588hguj
                        first_established_ts: 1724757940000
                        last_established_ts: 1724757940000
                        dataset_ids:
                        - 66b61a54dd6e6e1767a897fd
                        batch_ids:
                        - 01J5WGCRZCK5C0Y30SKPZ6KN11
                      - xid_pair:
                        - ABXZDAFGYY
                        - BVR478768HGFJHVJK
                        first_established_ts: 1724757940000
                        last_established_ts: 1724757940000
                        dataset_ids:
                        - 66b61a54dd6e6e1ea7a89713
                        batch_ids:
                        - 01J5WGCRZCK5C0Y30SKPA21612
                    unprocessed_composite_xids: []
                    algo_type: STITCH_ALL
        '400':
          description: Bad Request from the client
          x-summary: Bad Request - Invalid Input
          headers:
            content-type:
              description: Response is a JSON document with UTF-8 encoding
              schema:
                type: string
                default: application/json;version=2.2.1;charset=utf-8;charset=utf-8
            cache-control:
              description: caching policy for response
              schema:
                type: string
                default: no-cache
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceErrorStatus'
              example:
                reason: 'Validation error Request id: id-api-http-8qUg8oSANC.'
                message: Graph Request Invalid - projection types available are [graph|set].
        '401':
          description: IMS token is missing required scope.
          x-summary: Unauthorized - Missing or Invalid Scope
          headers:
            content-type:
              description: Response is a JSON document with UTF-8 encoding
              schema:
                type: string
                default: application/json
            cache-control:
              description: caching policy for response
              schema:
                type: string
                default: no-cache
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceErrorStatus'
              example:
                title: UnauthorizedAccessInvalidScope
                status: 401
                detail: Token does not have valid scope. Either 'acp_core_identity' scope or 'acp_foundation' scope is required.
        '403':
          description: Insufficient permissions
          x-summary: Unauthorized - Missing Permissions
          headers:
            content-type:
              description: Response is a JSON document with UTF-8 encoding
              schema:
                type: string
                default: application/json
            cache-control:
              description: caching policy for response
              schema:
                type: string
                default: no-cache
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceErrorStatus'
              example:
                type: https://ns.adobe.com/aep/errors/UIS-4064-403
                status: 403
                title: Insufficient permissions
                detail: 'The authorization token provided in the request does not have the permissions to access: READ IdentityGraph. Please contact your system administrator to fix this issue.

                  '
                report:
                  tenantInfo:
                    imsOrgId: 09A55EBC5639E6017F000101@AdobeOrg,
                    sandboxId: 8129954a-fa83-43ba-a995-4bfa8373ba2b,
                    sandboxName: Prod
                  additionalContext: null
                  errorChain: []
        '429':
          description: Request rate is large
          x-summary: Too Many Requests - Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceErrorStatus'
              example:
                title: RequestRateTooLarge
                status: 429
                detail: Request rate is large. Please try again later.
        '500':
          description: Unexpected Internal application error
          x-summary: Server Error - Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceErrorStatus'
              example:
                title: InternalError
                status: 500
      x-codegen-request-body-name: body
components:
  schemas:
    Id:
      type: string
      description: Identity string as returned by /identity/identity GET api.
    GraphResponseEdge:
      type: object
      properties:
        composite_xid_pair:
          type: array
          items:
            $ref: '#/components/schemas/GraphResponseCompositeXid'
        xid_pair:
          type: array
          items:
            $ref: '#/components/schemas/Id'
        first_established_ts:
          type: integer
        last_established_ts:
          type: integer
        dataset_ids:
          type: array
          description: 'This field is returned for requests with require_edge_meta_data: true

            '
          items:
            type: string
        batch_ids:
          type: array
          description: 'This field is returned for requests with require_edge_meta_data: true

            '
          items:
            type: string
    GraphResponseVerticle:
      type: object
      properties:
        last_updated_ts:
          type: integer
        composite_xid:
          $ref: '#/components/schemas/GraphResponseCompositeXid'
        xid:
          $ref: '#/components/schemas/Id'
    GraphRequestTraverse:
      type: object
      properties:
        predicate:
          type: array
          items:
            $ref: '#/components/schemas/GraphPredicate'
    GraphRequestBase:
      type: object
      properties:
        projection_type:
          type: string
          description: 'This is a required field dictating the format of the returned graph: a set of members or a graph with vertices and edges.

            '
          enum:
          - set
          - graph
        graph_type:
          type: string
        traverse:
          type: array
          items:
            $ref: '#/components/schemas/GraphRequestTraverse'
        filter:
          type: array
          items:
            $ref: '#/components/schemas/GraphRequestFilter'
        aam_properties:
          type: object
          description: 'This filter cannot be used with projection_type: graph.

            '
          properties:
            return_data_sources:
              type: boolean
        require_edge_meta_data:
          type: boolean
          description: 'This is and optional field that is used to add edge meta data in the response, such as dataset_ids and batch_ids.

            It will only apply if the requested projection_type is graph.

            '
    GraphRequestXids:
      allOf:
      - type: object
        properties:
          xids:
            type: array
            items:
              $ref: '#/components/schemas/Id'
            minItems: 1
            maxItems: 1000
      - $ref: '#/components/schemas/GraphRequestBase'
    GraphRequestFilter:
      type: object
      properties:
        predicate:
          type: array
          items:
            $ref: '#/components/schemas/GraphPredicate'
        order_by:
          type: string
        limit:
          type: string
    GraphRequestCompositeXids:
      allOf:
      - type: object
        properties:
          composite_xids:
            type: array
            items:
              $ref: '#/components/schemas/GraphResponseCompositeXid'
            minItems: 1
            maxItems: 1000
      - $ref: '#/components/schemas/GraphRequestBase'
    GraphResponseCompositeXid:
      type: object
      properties:
        nsid:
          description: Namespace id
          type: integer
        id:
          description: Identity in given namespace
          type: string
        ns:
          description: Namespace code
          type: string
    ServiceErrorStatus:
      type: object
      properties:
        title:
          type: string
          description: A short, human-readable summary of the problem type
        status:
          type: integer
          description: HTTP error code describing the problem
        detail:
          type: string
          description: 'A human-readable explanation specific to this occurrence of the

            problem

            '
        type:
          type: string
          description: Link to error type
        reason:
          type: string
          description: A short, human-readable summary of the problem type
        message:
          type: string
          description: 'A human-readable explanation specific to this occurrence of the

            problem

            '
        report:
          type: object
          properties:
            tenantInfo:
              description: Sandbox details
              type: object
              properties:
                imsOrgId:
                  type: string
                sandboxId:
                  type: string
                sandboxName:
                  type: string
            additionalContext:
              description: Additional details relevant to the error.
              type: object
              properties:
                userId:
                  type: string
            errorChain:
              description: Where multiple errors occurred leading up to the returned response, additional errors are included in this field.
              type: array
              items:
                type: object
                properties:
                  serviceId:
                    type: string
                  errorCode:
                    type: string
                  invokingServiceId:
                    type: string
                  errorMessage:
                    type: string
                  unixTimeStampMs:
                    type: integer
    GraphResponse:
      type: object
      properties:
        version:
          type: string
        graphs:
          type: object
          properties:
            vertices:
              type: array
              description: 'This field is returned for requests with projection_type: graph <br/><br/>

                The returned identities are formatted to match the request (composite_xid/xid)

                '
              items:
                $ref: '#/components/schemas/GraphResponseVerticle'
            edges:
              type: array
              description: 'This field is returned for requests with projection_type: graph <br/><br/>

                The returned identities are formatted to match the request (composite_xid/xid)

                '
              items:
                $ref: '#/components/schemas/GraphResponseEdge'
            members:
              type: array
              description: 'This field is returned for requests with projection_type: set <br/><br/>

                The returned identities are formatted to match the request (composite_xid/xid)

                '
              items:
                oneOf:
                - $ref: '#/components/schemas/GraphResponseCompositeXid'
                - $ref: '#/components/schemas/Id'
            datasources:
              type: array
              items:
                $ref: '#/components/schemas/GraphResponseDataSources'
        unprocessed_composite_xids:
          type: array
          description: 'This field is returned when the requested identity is formatted as composite_xid

            '
          items:
            $ref: '#/components/schemas/GraphResponseCompositeXid'
        unprocessed_xids:
          type: array
          description: 'This field is returned when the requested identity is formatted as xid

            '
          items:
            $ref: '#/components/schemas/Id'
    GraphResponseDataSources:
      type: object
      properties:
        composite_xid:
          $ref: '#/components/schemas/GraphResponseCompositeXid'
        xid:
          $ref: '#/components/schemas/Id'
        ds_ids:
          type: array
          items:
            type: integer
    GraphPredicate:
      type: object
      properties:
        v_prop:
          type: string
        e_prop:
          type: string
        op:
          type: string
        value:
          type: string
  parameters:
    x-api-key:
      name: x-api-key
      in: header
      description: 'The API key which can be copied from your Experience Platform

        integration. For more information on how to obtain this value, visit the

        [authentication

        tutorial](http://www.adobe.com/go/platform-api-authentication-en).

        '
      required: true
      schema:
        type: string
    content-type:
      name: Content-Type
      in: header
      description: The type of content being sent in the request. Use 'application/json'.
      required: true
      schema:
        type: string
        default: application/json
    x-sandbox-name:
      name: x-sandbox-name
      in: header
      description: 'The the all-lowercase name of the sandbox the operation will take place in. If unspecified, falls back to the default production sandbox (usually "prod"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.

        '
      schema:
        type: string
        example: prod
    authorization:
      name: Authorization
      in: header
      description: 'The access token which can be copied from your Experience Platform

        integration, prefixed with "Bearer ". For more information on how to

        obtain this value, visit the [authentication

        tutorial](http://www.adobe.com/go/platform-api-authentication-en).

        '
      required: true
      schema:
        type: string
    x-request-id:
      name: x-request-id
      in: header
      description: Request id to be used for tracing this request.
      schema:
        type: string
    x-gw-ims-org-id:
      name: x-gw-ims-org-id
      in: header
      description: 'The Organization ID which can be copied from your Experience Platform

        integration. For more information on how to obtain this value, visit the

        [authentication

        tutorial](http://www.adobe.com/go/platform-api-authentication-en).

        '
      required: true
      schema:
        type: string
x-original-swagger-version: '2.0'