HTTP API
When you create an account on iroh.network you get access to 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:
This api is hosted & provided to all iroh.network accounts. Sign up to get an account.
Authentication
POSTget an API access token (UCAN)
/token
Request
POST
/tokencurl -G https://iroh.network/api/token \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "API access token",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"token": {
"type": "string"
}
}
}
}
}
}
GETdescribe the current logged-in user
/user/me
Request
GET
/user/mecurl -G https://iroh.network/api/user/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"
},
"user_role": {
"type": "string",
"enum": [
"ADMIN",
"USER"
]
},
"pub_key": {
"type": "string"
},
"profile_photo_url_small": {
"type": "string"
},
"profile_photo_url_large": {
"type": "string"
}
}
}
}
}
}
GETlist projects available to the current user
/user/me/projects
Multiple status values can be provided with comma separated strings
Request
GET
/user/me/projectscurl -G https://iroh.network/api/user/me/projects \
-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": {
"name": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"owner_id": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
}
}
}
}
}
}
GETlist projects for a given user
/projects/:username
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
GET
/projects/:usernamecurl -G https://iroh.network/api/projects/:username \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"owner_id": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
}
}
}
}
}
}
PUTupdate project details
/projects/:username
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
PUT
/projects/:usernamecurl -G https://iroh.network/api/projects/:username \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"owner_id": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
}
}
}
}
}
POSTcreate a project
/projects/:username
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
POST
/projects/:usernamecurl -G https://iroh.network/api/projects/:username \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"owner_id": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
}
}
}
}
}
DELETEdelete a project
/projects/:username
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
DELETE
/projects/:usernamecurl -G https://iroh.network/api/projects/:username \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "success"
}
GETget project details
/projects/:username/:project
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
GET
/projects/:username/:projectcurl -G https://iroh.network/api/projects/:username/:project \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"owner_id": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
}
}
}
}
}
GETproject settings
/projects/:username/:project/settings
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
GET
/projects/:username/:project/settingscurl -G https://iroh.network/api/projects/:username/:project/settings \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"http_gateway_enabled": {
"type": "boolean"
}
}
}
}
}
}
PUTproject settings
/projects/:username/:project/settings
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
PUT
/projects/:username/:project/settingscurl -G https://iroh.network/api/projects/:username/:project/settings \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "success",
"content": {
"application/json": null
}
}
GETlist project documents
/docs/:username/:project
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
GET
/docs/:username/:projectcurl -G https://iroh.network/api/docs/:username/:project \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "user's docs",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"doc_id": {
"type": "string"
},
"name": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"author_id": {
"type": "string"
},
"hash": {
"type": "string"
},
"content_length": {
"type": "integer"
},
"timestamp": {
"type": "integer"
}
}
}
}
}
}
}
}
}
}
POSTcreate a new document
/docs/:username/:project
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
POST
/docs/:username/:projectcurl -G https://iroh.network/api/docs/:username/:project \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "created document",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"doc_id": {
"type": "string"
},
"name": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"author_id": {
"type": "string"
},
"hash": {
"type": "string"
},
"content_length": {
"type": "integer"
},
"timestamp": {
"type": "integer"
}
}
}
}
}
}
}
}
}
GETget a document
/docs/:username/:project/:doc_id
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
doc_id- Type
- string
- Description
a document identifier
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
GET
/docs/:username/:project/:doc_idcurl -G https://iroh.network/api/docs/:username/:project/:doc_id \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "document",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"doc_id": {
"type": "string"
},
"name": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"author_id": {
"type": "string"
},
"hash": {
"type": "string"
},
"content_length": {
"type": "integer"
},
"timestamp": {
"type": "integer"
}
}
}
}
}
}
}
}
}
}
POSTset a key in a document
/docs/:username/:project/:doc_id/set
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
doc_id- Type
- string
- Description
a document identifier
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
POST
/docs/:username/:project/:doc_id/setcurl -G https://iroh.network/api/docs/:username/:project/:doc_id/set \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "updated document",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"doc_id": {
"type": "string"
},
"name": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"author_id": {
"type": "string"
},
"hash": {
"type": "string"
},
"content_length": {
"type": "integer"
},
"timestamp": {
"type": "integer"
}
}
}
}
}
}
}
}
}
DELETEdelete a prefix in a document
/docs/:username/:project/:doc_id/del
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
doc_id- Type
- string
- Description
a document identifier
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
DELETE
/docs/:username/:project/:doc_id/delcurl -G https://iroh.network/api/docs/:username/:project/:doc_id/del \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "updated document",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"doc_id": {
"type": "string"
},
"name": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"author_id": {
"type": "string"
},
"hash": {
"type": "string"
},
"content_length": {
"type": "integer"
},
"timestamp": {
"type": "integer"
}
}
}
}
}
}
}
}
}
DELETEdelete an entire document
/docs/:username/:project/:doc_id/drop
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
doc_id- Type
- string
- Description
a document identifier
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
DELETE
/docs/:username/:project/:doc_id/dropcurl -G https://iroh.network/api/docs/:username/:project/:doc_id/drop \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "document deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deleted": {
"type": "boolean"
}
}
}
}
}
}
GETget a document name
/docs/:username/:project/:doc_id/name
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
doc_id- Type
- string
- Description
a document identifier
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
GET
/docs/:username/:project/:doc_id/namecurl -G https://iroh.network/api/docs/:username/:project/:doc_id/name \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "user's docs",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"doc_id": {
"type": "string"
},
"name": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"author_id": {
"type": "string"
},
"hash": {
"type": "string"
},
"content_length": {
"type": "integer"
},
"timestamp": {
"type": "integer"
}
}
}
}
}
}
}
}
}
}
POSTcreate a new document
/docs/:username/:project/:doc_id/name
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
doc_id- Type
- string
- Description
a document identifier
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
POST
/docs/:username/:project/:doc_id/namecurl -G https://iroh.network/api/docs/:username/:project/:doc_id/name \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "created document",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"doc_id": {
"type": "string"
},
"name": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"author_id": {
"type": "string"
},
"hash": {
"type": "string"
},
"content_length": {
"type": "integer"
},
"timestamp": {
"type": "integer"
}
}
}
}
}
}
}
}
}
POSTshare access to a document
/docs/:username/:project/:doc_id/share
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
doc_id- Type
- string
- Description
a document identifier
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
POST
/docs/:username/:project/:doc_id/sharecurl -G https://iroh.network/api/docs/:username/:project/:doc_id/share \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "document ticket",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"doc_id": {
"type": "string",
"length": 52
},
"ticket": {
"type": "string"
}
}
}
}
}
}
POSTjoin a document from a share ticket
/docs/:username/:project/:doc_id/join
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
doc_id- Type
- string
- Description
a document identifier
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
POST
/docs/:username/:project/:doc_id/joincurl -G https://iroh.network/api/docs/:username/:project/:doc_id/join \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "joined document",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"doc_id": {
"type": "string"
},
"name": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"author_id": {
"type": "string"
},
"hash": {
"type": "string"
},
"content_length": {
"type": "integer"
},
"timestamp": {
"type": "integer"
}
}
}
}
}
}
}
}
}
GETlist a user's blobs
/blobs/:username/:project
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
offset- Type
- string
- Description
- Name
limit- Type
- string
- Description
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
GET
/blobs/:username/:projectcurl -G https://iroh.network/api/blobs/:username/:project \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "blob list",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"hash": {
"type": "string"
},
"size": {
"type": "integer"
}
}
}
}
}
}
}
POSTdelete a n array of blob hashes from this project
/blobs/:username/:project
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
POST
/blobs/:username/:projectcurl -G https://iroh.network/api/blobs/:username/:project \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "success",
"content": {
"application/json": null
}
}
DELETEupload a blob or collection to a project
/blobs/:username/:project
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
DELETE
/blobs/:username/:projectcurl -G https://iroh.network/api/blobs/:username/:project \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "success",
"content": {
"application/json": null
}
}
DELETEdelete a single blob
/blobs/:username/:project/:hash
Parameters
- Name
username- Type
- string
- Description
the username or team name to scope the request to
- Name
project- Type
- string
- Description
Name of the project
- Name
hash- Type
- string
- Description
an iroh hash
- Name
limit- Type
- integer
- Description
Limit the number of attachments returned.
Request
DELETE
/blobs/:username/:project/:hashcurl -G https://iroh.network/api/blobs/:username/:project/:hash \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
Response
{
"description": "success",
"content": {
"application/json": null
}
}