# Communication

This API suite focuses on managing connections within an Identus agent system, with different authentication keys for different subsystems or access levels. The communication layer is mostly managed via DID Comm v2 (within Identus)

## Retrieve a list of connections between Alice and Bob

<mark style="color:green;">`GET`</mark> `/api/v1/p2p`

\<Description of the endpoint>

**Headers**

| Name          | Value                        |
| ------------- | ---------------------------- |
| Content-Type  | `application/json`           |
| Authorization | `apikey = {Alice's API key}` |

**Body**

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "data": [
        {
            "connectionId": "af7a1d39-a969-4b0c-9399-03b42229984a",
            "thid": "af7a1d39-a969-4b0c-9399-03b42229984a",
            "label": "p2p initiated by snet123",
            "goal": "p2p connection",
            "role": "Inviter",
            "state": "InvitationGenerated",
            "invitation": {
                "id": "af7a1d39-a969-4b0c-9399-03b42229984a",
                "type": "https://didcomm.org/out-of-band/2.0/invitation",
                "from": "did:peer:2.Ez6LStoRKnFA7kTJo3Acj1AsPmXUzDV9VKULWjCpbeCqbR9vq.Vz6MkvXitkonf2UHRkKoNFUMggHMivkHsXZz2hRHaRKfSXxJi.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
                "invitationUrl": "https://my.domain.com/path?_oob=eyJpZCI6ImFmN2ExZDM5LWE5NjktNGIwYy05Mzk5LTAzYjQyMjI5OTg0YSIsInR5cGUiOiJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzIuMC9pbnZpdGF0aW9uIiwiZnJvbSI6ImRpZDpwZWVyOjIuRXo2TFN0b1JLbkZBN2tUSm8zQWNqMUFzUG1YVXpEVjlWS1VMV2pDcGJlQ3FiUjl2cS5WejZNa3ZYaXRrb25mMlVIUmtLb05GVU1nZ0hNaXZrSHNYWnoyaFJIYVJLZlNYeEppLlNleUowSWpvaVpHMGlMQ0p6SWpwN0luVnlhU0k2SW1oMGRIQTZMeTlvYjNOMExtUnZZMnRsY2k1cGJuUmxjbTVoYkRvNE1UQXdMMlJwWkdOdmJXMGlMQ0p5SWpwYlhTd2lZU0k2V3lKa2FXUmpiMjF0TDNZeUlsMTlmUSIsImJvZHkiOnsiZ29hbCI6InAycCBjb25uZWN0aW9uIiwiYWNjZXB0IjpbXX19"
            },
            "createdAt": "2024-10-03T12:40:35.835452Z",
            "metaRetries": 5,
            "self": "af7a1d39-a969-4b0c-9399-03b42229984a",
            "kind": "Connection"
        },
        {
            "connectionId": "add6d381-1180-484c-bc40-178d362346c0",
            "thid": "add6d381-1180-484c-bc40-178d362346c0",
            "label": "p2p initiated by snet for ping",
            "goal": "p2p connection",
            "myDid": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
            "theirDid": "did:peer:2.Ez6LSn5R6dTUZzq3eJSA4jnYJjcDM9A96yWQB9SCnMay1pdD2.Vz6Mkik12YQct7UEQeMeC6RTjjBHswsVWTRrq7GSSXPgLutEp.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
            "role": "Inviter",
            "state": "ConnectionResponseSent",
            "invitation": {
                "id": "add6d381-1180-484c-bc40-178d362346c0",
                "type": "https://didcomm.org/out-of-band/2.0/invitation",
                "from": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
                "invitationUrl": "https://my.domain.com/path?_oob=eyJpZCI6ImFkZDZkMzgxLTExODAtNDg0Yy1iYzQwLTE3OGQzNjIzNDZjMCIsInR5cGUiOiJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzIuMC9pbnZpdGF0aW9uIiwiZnJvbSI6ImRpZDpwZWVyOjIuRXo2TFNxcEZVSjV2VzZZVzJENjdxWmlYTnlidmQ3RDJ2cUhUQXZCNEhVakxkQU5vYi5WejZNa3VQY1QxVnZYUGhyQm1NUkpLell3NjZrZ3JCUWRDaUQxTEIxV2JGdkw3Z3g3LlNleUowSWpvaVpHMGlMQ0p6SWpwN0luVnlhU0k2SW1oMGRIQTZMeTlvYjNOMExtUnZZMnRsY2k1cGJuUmxjbTVoYkRvNE1UQXdMMlJwWkdOdmJXMGlMQ0p5SWpwYlhTd2lZU0k2V3lKa2FXUmpiMjF0TDNZeUlsMTlmUSIsImJvZHkiOnsiZ29hbCI6InAycCBjb25uZWN0aW9uIiwiYWNjZXB0IjpbXX19"
            },
            "createdAt": "2024-10-03T12:44:15.81145Z",
            "updatedAt": "2024-10-03T12:44:20.293958Z",
            "metaRetries": 5,
            "self": "add6d381-1180-484c-bc40-178d362346c0",
            "kind": "Connection"
        }
    ]
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "data": null,
    "status": 401,
    "message": "Invalid key"
}
```

{% endtab %}
{% endtabs %}

## Retrieve a specific connection maintained for Alice and Bob

<mark style="color:green;">`GET`</mark> `/api/v1/p2p/{id_connection}`

\<Description of the endpoit>

**Headers**

| Name          | Value                        |
| ------------- | ---------------------------- |
| Content-Type  | `application/json`           |
| Authorization | `apikey = {Alice's API key}` |

**Body**

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "data": {
        "connectionId": "add6d381-1180-484c-bc40-178d362346c0",
        "thid": "add6d381-1180-484c-bc40-178d362346c0",
        "label": "p2p initiated by snet for ping",
        "goal": "p2p connection",
        "myDid": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
        "theirDid": "did:peer:2.Ez6LSn5R6dTUZzq3eJSA4jnYJjcDM9A96yWQB9SCnMay1pdD2.Vz6Mkik12YQct7UEQeMeC6RTjjBHswsVWTRrq7GSSXPgLutEp.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
        "role": "Inviter",
        "state": "ConnectionResponseSent",
        "invitation": {
            "id": "add6d381-1180-484c-bc40-178d362346c0",
            "type": "https://didcomm.org/out-of-band/2.0/invitation",
            "from": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
            "invitationUrl": "https://my.domain.com/path?_oob=eyJpZCI6ImFkZDZkMzgxLTExODAtNDg0Yy1iYzQwLTE3OGQzNjIzNDZjMCIsInR5cGUiOiJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzIuMC9pbnZpdGF0aW9uIiwiZnJvbSI6ImRpZDpwZWVyOjIuRXo2TFNxcEZVSjV2VzZZVzJENjdxWmlYTnlidmQ3RDJ2cUhUQXZCNEhVakxkQU5vYi5WejZNa3VQY1QxVnZYUGhyQm1NUkpLell3NjZrZ3JCUWRDaUQxTEIxV2JGdkw3Z3g3LlNleUowSWpvaVpHMGlMQ0p6SWpwN0luVnlhU0k2SW1oMGRIQTZMeTlvYjNOMExtUnZZMnRsY2k1cGJuUmxjbTVoYkRvNE1UQXdMMlJwWkdOdmJXMGlMQ0p5SWpwYlhTd2lZU0k2V3lKa2FXUmpiMjF0TDNZeUlsMTlmUSIsImJvZHkiOnsiZ29hbCI6InAycCBjb25uZWN0aW9uIiwiYWNjZXB0IjpbXX19"
        },
        "createdAt": "2024-10-03T12:44:15.81145Z",
        "updatedAt": "2024-10-03T12:44:20.293958Z",
        "metaRetries": 5,
        "self": "add6d381-1180-484c-bc40-178d362346c0",
        "kind": "Connection"
    }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "data": null,
    "status": 401,
    "message": "Invalid key"
}
```

{% endtab %}
{% endtabs %}

## Create a connection invitation, handling out-of-band invitations

<mark style="color:green;">`POST`</mark> `/api/v1/p2p/invite`

\<Description of the endpoint>

**Headers**

| Name          | Value                        |
| ------------- | ---------------------------- |
| Content-Type  | `application/json`           |
| Authorization | `apikey = {Alice's API key}` |

**Body**

| Name   | Type   | Description                                 |
| ------ | ------ | ------------------------------------------- |
| `from` | string | This is to generate a nicely formed message |

**Response**

{% tabs %}
{% tab title="201" %}

```json
 "data": {
        "connectionId": "af7a1d39-a969-4b0c-9399-03b42229984a",
        "thid": "af7a1d39-a969-4b0c-9399-03b42229984a",
        "label": "p2p initiated by snet123",
        "goal": "p2p connection",
        "role": "Inviter",
        "state": "InvitationGenerated",
        "invitation": {
            "id": "af7a1d39-a969-4b0c-9399-03b42229984a",
            "type": "https://didcomm.org/out-of-band/2.0/invitation",
            "from": "did:peer:2.Ez6LStoRKnFA7kTJo3Acj1AsPmXUzDV9VKULWjCpbeCqbR9vq.Vz6MkvXitkonf2UHRkKoNFUMggHMivkHsXZz2hRHaRKfSXxJi.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
            "invitationUrl": "https://my.domain.com/path?_oob=eyJpZCI6ImFmN2ExZDM5LWE5NjktNGIwYy05Mzk5LTAzYjQyMjI5OTg0YSIsInR5cGUiOiJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzIuMC9pbnZpdGF0aW9uIiwiZnJvbSI6ImRpZDpwZWVyOjIuRXo2TFN0b1JLbkZBN2tUSm8zQWNqMUFzUG1YVXpEVjlWS1VMV2pDcGJlQ3FiUjl2cS5WejZNa3ZYaXRrb25mMlVIUmtLb05GVU1nZ0hNaXZrSHNYWnoyaFJIYVJLZlNYeEppLlNleUowSWpvaVpHMGlMQ0p6SWpwN0luVnlhU0k2SW1oMGRIQTZMeTlvYjNOMExtUnZZMnRsY2k1cGJuUmxjbTVoYkRvNE1UQXdMMlJwWkdOdmJXMGlMQ0p5SWpwYlhTd2lZU0k2V3lKa2FXUmpiMjF0TDNZeUlsMTlmUSIsImJvZHkiOnsiZ29hbCI6InAycCBjb25uZWN0aW9uIiwiYWNjZXB0IjpbXX19"
        },
        "createdAt": "2024-10-03T12:40:35.835452249Z",
        "metaRetries": 5,
        "self": "af7a1d39-a969-4b0c-9399-03b42229984a",
        "kind": "Connection"
    }
```

{% endtab %}

{% tab title="401" %}

```json
{
    "data": null,
    "status": 401,
    "message": "Invalid key"
}
```

{% endtab %}
{% endtabs %}

## Accept a specific connection invitation

<mark style="color:green;">`POST`</mark> `/api/v1/p2p/accept`

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/json`         |
| Authorization | `apikey = {Bob's API key}` |

**Body**

| Name         | Type   | Description                                        |
| ------------ | ------ | -------------------------------------------------- |
| `invitation` | string | The out of band invitation (eg: eyJpZCI6Ij...dfX0) |

**Response**

{% tabs %}
{% tab title="201" %}

```json
{
  "data":
    {
        "connectionId": "25cbc847-9df9-4d96-926c-20956d7ca5bc",
        "thid": "add6d381-1180-484c-bc40-178d362346c0",
        "goal": "p2p connection",
        "myDid": "did:peer:2.Ez6LSn5R6dTUZzq3eJSA4jnYJjcDM9A96yWQB9SCnMay1pdD2.Vz6Mkik12YQct7UEQeMeC6RTjjBHswsVWTRrq7GSSXPgLutEp.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
        "theirDid": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
        "role": "Invitee",
        "state": "ConnectionResponseReceived",
        "invitation": {
            "id": "add6d381-1180-484c-bc40-178d362346c0",
            "type": "https://didcomm.org/out-of-band/2.0/invitation",
            "from": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
            "invitationUrl": "https://my.domain.com/path?_oob=eyJpZCI6ImFkZDZkMzgxLTExODAtNDg0Yy1iYzQwLTE3OGQzNjIzNDZjMCIsInR5cGUiOiJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzIuMC9pbnZpdGF0aW9uIiwiZnJvbSI6ImRpZDpwZWVyOjIuRXo2TFNxcEZVSjV2VzZZVzJENjdxWmlYTnlidmQ3RDJ2cUhUQXZCNEhVakxkQU5vYi5WejZNa3VQY1QxVnZYUGhyQm1NUkpLell3NjZrZ3JCUWRDaUQxTEIxV2JGdkw3Z3g3LlNleUowSWpvaVpHMGlMQ0p6SWpwN0luVnlhU0k2SW1oMGRIQTZMeTlvYjNOMExtUnZZMnRsY2k1cGJuUmxjbTVoYkRvNE1UQXdMMlJwWkdOdmJXMGlMQ0p5SWpwYlhTd2lZU0k2V3lKa2FXUmpiMjF0TDNZeUlsMTlmUSIsImJvZHkiOnsiZ29hbCI6InAycCBjb25uZWN0aW9uIiwiYWNjZXB0IjpbXX19"
        },
        "createdAt": "2024-10-03T12:44:17.529663Z",
        "updatedAt": "2024-10-03T12:44:20.284989Z",
        "metaRetries": 5,
        "self": "25cbc847-9df9-4d96-926c-20956d7ca5bc",
        "kind": "Connection"
    }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "data": null,
    "status": 401,
    "message": "Invalid key"
}
```

{% endtab %}
{% endtabs %}

## Creates a communication between two peers in custodial mode

<mark style="color:green;">`POST`</mark> `/api/v1/p2p/custodial/connect`

Creates a connection between two peers, in a custodial mode, where the owner (generally peer1) can then act as issuer, verifier, etc...

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `None`             |

**Body**

| Name         | Type   | Description                             |
| ------------ | ------ | --------------------------------------- |
| `key_peer1`  | string | the private authentication key of peer1 |
| `key_peer2`  | string | the private authentication key of peer1 |
| `name_peer1` | string | name of peer1                           |
| `name_peer2` | string | name of peer2                           |

**Response**

{% tabs %}
{% tab title="201" %}

```json
{
    "data": {
        "from": "snet",
        "anonDidFrom": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
        "connection_id_from": "add6d381-1180-484c-bc40-178d362346c0",
        "to": "ping",
        "anonDidTo": "did:peer:2.Ez6LSn5R6dTUZzq3eJSA4jnYJjcDM9A96yWQB9SCnMay1pdD2.Vz6Mkik12YQct7UEQeMeC6RTjjBHswsVWTRrq7GSSXPgLutEp.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
        "connection_id_to": "25cbc847-9df9-4d96-926c-20956d7ca5bc",
        "thid": "add6d381-1180-484c-bc40-178d362346c0",
        "isAccepted": true
    }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://incubiq.gitbook.io/opensourceais/identity-agent-lib/apis/communication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.