HTTP API

Iroh anchors come with an HTTP API. You can use this API to bridge from the iroh protocol to HTTP, for both end-user use and administrative purposes.

This documentation is also available as an OpenAPI Specification:

OpenAPI Spec File

This api is hosted & provided to all iroh.network accounts. Sign up for the beta to get an account.

Authentication

GET/health

get API health status

Request

GET

/health

curl -G https://iroh.network/api/health \
  -H "Authorization: Bearer {token}" \
  -d conversation_id="xgQQXg3hrtjh7AvZ" \
  -d limit=10

Response

{
"description": "healthy service"
}

POST/token

get an API access token (UCAN)

Request

POST

/token

curl -G https://iroh.network/api/token \
  -H "Authorization: Bearer {token}" \
  -d conversation_id="xgQQXg3hrtjh7AvZ" \
  -d limit=10

Response

{
"description": "API access token",
"content": {
    "appliction/json": {
        "schema": {
            "type": "object",
            "properties": {
                "token": {
                    "type": "string"
                }
            }
        }
    }
}
}

GET/me

describe the current logged-in user

Request

GET

/me

curl -G https://iroh.network/api/me \
  -H "Authorization: Bearer {token}" \
  -d conversation_id="xgQQXg3hrtjh7AvZ" \
  -d limit=10

Response

{
"description": "session user",
"content": {
    "application/json": {
        "schema": {
            "type": "object",
            "properties": {
                "user_id": {
                    "type": "string",
                    "format": "uuid",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "updated_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "name": {
                    "type": "string",
                    "format": null
                },
                "user_role": {
                    "type": "string",
                    "enum": [
                        "ADMIN",
                        "USER"
                    ]
                },
                "pub_key": {
                    "type": "string",
                    "format": null
                },
                "profile_photo_url_small": {
                    "type": "string"
                },
                "profile_photo_url_large": {
                    "type": "string"
                }
            }
        }
    }
}
}

GET/networks

list networks available to the current user

Multiple status values can be provided with comma separated strings

Request

GET

/networks

curl -G https://iroh.network/api/networks \
  -H "Authorization: Bearer {token}" \
  -d conversation_id="xgQQXg3hrtjh7AvZ" \
  -d limit=10

Response

{
"description": "successful operation",
"content": {
    "application/json": {
        "schema": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "network_id": {
                        "type": "string",
                        "format": "uuid",
                        "example": "550e8400-e29b-41d4-a716-446655440000"
                    },
                    "pretty_name": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "anchor_url": {
                        "type": "string"
                    },
                    "config": {
                        "type": "object",
                        "properties": {
                            "network_id": {
                                "type": "string",
                                "format": "uuid",
                                "example": "550e8400-e29b-41d4-a716-446655440000"
                            },
                            "updated_at": {
                                "type": "string",
                                "format": "date-time"
                            },
                            "accept_content": {
                                "type": "boolean"
                            },
                            "provide_content": {
                                "type": "string"
                            },
                            "connection_policy": null,
                            "kubo_egress": null,
                            "kubo_ingress": null
                        }
                    }
                }
            }
        }
    }
}
}

GET/networks/{network_name}/collections

list network collections

returns a

Parameters

Name
network_id
Type
string
Description
ID of the network to list collections for
Name
limit
Type
integer
Description
Limit the number of attachments returned.

Request

GET

/networks/{network_name}/collections

curl -G https://iroh.network/api/networks/{network_name}/collections \
  -H "Authorization: Bearer {token}" \
  -d conversation_id="xgQQXg3hrtjh7AvZ" \
  -d limit=10

Response

{
"description": "successful operation",
"content": {
    "application/json": {
        "schema": {
            "type": "object",
            "properties": {
                "pub_key": {
                    "type": "string",
                    "format": "",
                    "example": ""
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "updated_at": {
                    "type": "string",
                    "format": "date-time"
                },
                "created_by": {
                    "type": "string",
                    "format": "uuid",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                },
                "network_id": {
                    "type": "string",
                    "format": "uuid",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                },
                "cid": {
                    "type": "string",
                    "example": "bafkr4ihaehdb5yar357djzt4vzwd565w7rpluruvvwnhap7yknbydbadam"
                },
                "name": {
                    "type": "string"
                },
                "item_count": {
                    "type": "integer",
                    "format": "int32"
                },
                "size": {
                    "type": "integer",
                    "format": "uint64"
                },
                "signature": {
                    "type": "string"
                }
            }
        }
    }
}
}

POST/networks/{network_name}/collections

Update network settings

Parameters

Name
network_id
Type
string
Description
ID of the network to list collections for
Name
limit
Type
integer
Description
Limit the number of attachments returned.

Request

POST

/networks/{network_name}/collections

curl -G https://iroh.network/api/networks/{network_name}/collections \
  -H "Authorization: Bearer {token}" \
  -d conversation_id="xgQQXg3hrtjh7AvZ" \
  -d limit=10

DELETE/networks/{network_name}/collections

Deletes a network

Parameters

Name
network_id
Type
string
Description
ID of the network to list collections for
Name
limit
Type
integer
Description
Limit the number of attachments returned.

Request

DELETE

/networks/{network_name}/collections

curl -G https://iroh.network/api/networks/{network_name}/collections \
  -H "Authorization: Bearer {token}" \
  -d conversation_id="xgQQXg3hrtjh7AvZ" \
  -d limit=10

Response

{
"description": "Network deleted",
"content": {}
}