Jump toOrganization

Organization

Your organization, its settings, permission checks and brand assets.

post/v1/brand-assets

Upload brand asset

Needs settings.manage

Refused with validation_failed and a field error on /data or /content_type that says what to change (too large, not an image, the wrong type, animated, or an SVG using something a logo may not).

Request bodyBrandAssetUpload

content_typestringRequired
What the file is. It must match the bytes, which are checked.
One ofimage/pngimage/jpegimage/webpimage/svg+xmlat most 64 characters
datastringRequired
The file, base64 encoded (no data: prefix); at most 200 KB decoded.

Response201

idstring
objectstring
brand_asset
content_typestring
One ofimage/pngimage/jpegimage/webpimage/svg+xml
created_atstring
heightinteger or null
sha256string
sizeinteger
widthinteger or null

Status codes

201Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/brand-assets" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "image/png",
    "data": "data"
  }'

Response · 201

JSON

{
  "id": "id",
  "object": "brand_asset",
  "content_type": "image/png",
  "created_at": "2026-11-10T09:30:00.000Z",
  "height": 2,
  "sha256": "sha256",
  "size": 2,
  "width": 2
}

post/v1/permissions/check

Check permissions

Any key of this organization

Up to 50 {permission, workspace} pairs → booleans, for one screen.

Request bodyCheckRequest

checksPermissionQuery[]Required
at most 50 items
2 fields
- permissionstringRequired
- workspace_idstring or null

Response200

objectstring
list
dataPermissionResult[]
3 fields
- allowedboolean
- permissionstring
- workspace_idstring or null
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/permissions/check" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checks": [
      {
        "permission": "permission",
        "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
      }
    ]
  }'

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "allowed": true,
      "permission": "permission",
      "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

get/v1/settings

List settings

Any key of this organization

Response200

objectstring
list
dataSetting[]
12 fields
- editable_hereboolean
- keystring
- merge_rulestring
- modestring
  One ofdefaultenforced
- source_display_namestring or null
- source_tenant_idstring or null
- valueany
- ceilingnumber or null
- inherited_valueany
- own_valueany
- strictnessany[] or null
- value_schemaobject or null
  Any JSON object.
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/settings" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "ceiling": 0.5,
      "editable_here": true,
      "inherited_value": {},
      "key": "key",
      "merge_rule": "merge rule",
      "mode": "default",
      "own_value": {},
      "source_display_name": "source display name",
      "source_tenant_id": "source tenant id",
      "strictness": [
        {}
      ],
      "value": {},
      "value_schema": {}
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

get/v1/tenant

Tenant

Any key of this organization

Response200

idstring
objectstring
tenant
acting_via_delegationstring or null
kindstring
namestring
slugstring
statusstring
tierstring
One ofstandardprivacyhipaa
accessTenantAccess or null
How the caller actually entered: the console's delegation banner shows what the server used, not what the URL asked for.
4 fields
- delegationDelegationAccess or null
  4 fields
  idstring
  expires_atstring or null
  grantee_display_namestring
  grantee_tenant_idstring
- max_data_classstring
  One ofpublicinternalpiisensitivephi
- role_labelsstring[]
- viastring
  One ofmembershipdelegationservice_account

Status codes

200Successful Response
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/tenant" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "id": "ten_01jcs79j0bwr7ahcbyn0fjsmk6",
  "object": "tenant",
  "access": {
    "delegation": {
      "id": "id",
      "expires_at": "2026-11-10T09:30:00.000Z",
      "grantee_display_name": "grantee display name",
      "grantee_tenant_id": "grantee tenant id"
    },
    "max_data_class": "public",
    "role_labels": [
      "role label"
    ],
    "via": "membership"
  },
  "acting_via_delegation": "acting via delegation",
  "kind": "kind",
  "name": "Support triage",
  "slug": "support-triage",
  "status": "status",
  "tier": "standard"
}

post/v1/tenant/key_config/test

Test key config

Needs key.manage

Request bodyKeyConfigBody

key_uristringRequired
at least 1 charactersat most 2048 characters
accessobject or null
Any JSON object.
providerstring
aws_kmsDefault"aws_kms"

Response200

objectstring
live_test
okboolean
stepsLiveTestStep[]
3 fields
- messagestring or null
- okboolean
- stepstring

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/tenant/key_config/test" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access": {},
    "key_uri": "https://example.com",
    "provider": "aws_kms"
  }'

Response · 200

JSON

{
  "object": "live_test",
  "ok": true,
  "steps": [
    {
      "message": "Summarise today's open tickets.",
      "ok": true,
      "step": "step"
    }
  ]
}

get/v1/tenant/key_configs

List key configs

Needs key.manage

Every key configuration, newest first: a handful at most, so never paged.

Response200

objectstring
list
dataKeyConfig[]
12 fields
- objectstring
  key_config
- created_atstring
- healthstring
  One ofhealthydegradedunavailable
- health_checked_atstring or null
- in_useboolean
- key_uristring
- ownerstring
  One ofplatformtenant
- providerstring
- statusstring
  One ofpending_testactivereplacingretired
- created_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
- updated_atstring or null
- updated_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/tenant/key_configs" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "object": "key_config",
      "created_at": "2026-11-10T09:30:00.000Z",
      "created_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "health": "healthy",
      "health_checked_at": "2026-11-10T09:30:00.000Z",
      "in_use": true,
      "key_uri": "https://example.com",
      "owner": "platform",
      "provider": "anthropic",
      "status": "pending_test",
      "updated_at": "2026-11-10T09:30:00.000Z",
      "updated_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

post/v1/tenant/key_configs

Save key config

Needs key.manage

Saves only a configuration that passes; the answer is the test either way. ok: false means nothing was stored.

Request bodyKeyConfigBody

key_uristringRequired
at least 1 charactersat most 2048 characters
accessobject or null
Any JSON object.
providerstring
aws_kmsDefault"aws_kms"

Response201

objectstring
live_test
okboolean
stepsLiveTestStep[]
3 fields
- messagestring or null
- okboolean
- stepstring

Status codes

201Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/tenant/key_configs" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access": {},
    "key_uri": "https://example.com",
    "provider": "aws_kms"
  }'

Response · 201

JSON

{
  "object": "live_test",
  "ok": true,
  "steps": [
    {
      "message": "Summarise today's open tickets.",
      "ok": true,
      "step": "step"
    }
  ]
}

post/v1/tenant/storage_config/test

Test storage config

Needs storage.manage

Request bodyStorageConfigBody

bucketstringRequired
at least 3 charactersat most 63 charactersmatches ^[a-z0-9][a-z0-9.-]+[a-z0-9]$
accessobject or null
Any JSON object.
prefixstring
Default"mda/"at most 512 charactersmatches ^([A-Za-z0-9!_.*'()-]+/)*$
providerstring
s3Default"s3"
regionstring or null
at most 32 characters

Response200

objectstring
live_test
okboolean
stepsLiveTestStep[]
3 fields
- messagestring or null
- okboolean
- stepstring

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/tenant/storage_config/test" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access": {},
    "bucket": "bucket",
    "prefix": "mda/",
    "provider": "s3",
    "region": "region"
  }'

Response · 200

JSON

{
  "object": "live_test",
  "ok": true,
  "steps": [
    {
      "message": "Summarise today's open tickets.",
      "ok": true,
      "step": "step"
    }
  ]
}

get/v1/tenant/storage_configs

List storage configs

Needs storage.manage

Every storage configuration, newest first: a handful at most, so never paged.

Response200

objectstring
list
dataStorageConfig[]
12 fields
- objectstring
  storage_config
- bucketstring
- created_atstring
- in_useboolean
- ownerstring
  One ofplatformtenant
- prefixstring
- providerstring
- regionstring or null
- statusstring
  One ofpending_testactivereplacingretired
- created_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
- updated_atstring or null
- updated_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
has_moreboolean
next_cursorstring or null
facetsmap<string, map<string, integer>> or null
peoplemap<string, ActorRef> or null
5 fields
- idstring or null
- kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
- namestring or null
- avatar_versionstring or null
- emailstring or null
total_countinteger or null
total_count_exactboolean or null

Status codes

200Successful Response
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/tenant/storage_configs" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "data": [
    {
      "object": "storage_config",
      "bucket": "bucket",
      "created_at": "2026-11-10T09:30:00.000Z",
      "created_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "in_use": true,
      "owner": "platform",
      "prefix": "prefix",
      "provider": "anthropic",
      "region": "region",
      "status": "pending_test",
      "updated_at": "2026-11-10T09:30:00.000Z",
      "updated_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

post/v1/tenant/storage_configs

Save storage config

Needs storage.manage

Request bodyStorageConfigBody

bucketstringRequired
at least 3 charactersat most 63 charactersmatches ^[a-z0-9][a-z0-9.-]+[a-z0-9]$
accessobject or null
Any JSON object.
prefixstring
Default"mda/"at most 512 charactersmatches ^([A-Za-z0-9!_.*'()-]+/)*$
providerstring
s3Default"s3"
regionstring or null
at most 32 characters

Response201

objectstring
live_test
okboolean
stepsLiveTestStep[]
3 fields
- messagestring or null
- okboolean
- stepstring

Status codes

201Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X POST "https://api.mydeepagents.com/v1/tenant/storage_configs" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access": {},
    "bucket": "bucket",
    "prefix": "mda/",
    "provider": "s3",
    "region": "region"
  }'

Response · 201

JSON

{
  "object": "live_test",
  "ok": true,
  "steps": [
    {
      "message": "Summarise today's open tickets.",
      "ok": true,
      "step": "step"
    }
  ]
}

get/v1/brand-assets/{brand_asset_id}

Get brand asset

Any key of this organization

Path parameters

brand_asset_idstringRequired

Query parameters

vstring
A cache-busting version (the sha256); ignored.
at most 128 characters

Response200

Answers with a file (image/jpeg).

Status codes

200The image as stored, with its sandboxing headers.
304Not modified: If-None-Match named the current ETag.
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/brand-assets/bra_01jcnszzr4smwxzwkqzrvdn5km" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -o image.jpg

put/v1/settings/{key}

Put setting

Needs settings.manage

Path parameters

keystringRequired

Request bodySettingWrite

valueanyRequired
modestring
One ofdefaultenforcedDefault"default"

Response200

editable_hereboolean
keystring
merge_rulestring
modestring
One ofdefaultenforced
source_display_namestring or null
source_tenant_idstring or null
valueany
ceilingnumber or null
inherited_valueany
own_valueany
strictnessany[] or null
value_schemaobject or null
Any JSON object.

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X PUT "https://api.mydeepagents.com/v1/settings/{key}" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "default",
    "value": {}
  }'

Response · 200

JSON

{
  "ceiling": 0.5,
  "editable_here": true,
  "inherited_value": {},
  "key": "key",
  "merge_rule": "merge rule",
  "mode": "default",
  "own_value": {},
  "source_display_name": "source display name",
  "source_tenant_id": "source tenant id",
  "strictness": [
    {}
  ],
  "value": {},
  "value_schema": {}
}

delete/v1/settings/{key}

Delete setting

Needs settings.manage

Remove this tenant's own value: the parent's value (or the default) applies again, here and below. Idempotent; answers with the new effective setting.

Path parameters

keystringRequired

Response200

editable_hereboolean
keystring
merge_rulestring
modestring
One ofdefaultenforced
source_display_namestring or null
source_tenant_idstring or null
valueany
ceilingnumber or null
inherited_valueany
own_valueany
strictnessany[] or null
value_schemaobject or null
Any JSON object.

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X DELETE "https://api.mydeepagents.com/v1/settings/{key}" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "ceiling": 0.5,
  "editable_here": true,
  "inherited_value": {},
  "key": "key",
  "merge_rule": "merge rule",
  "mode": "default",
  "own_value": {},
  "source_display_name": "source display name",
  "source_tenant_id": "source tenant id",
  "strictness": [
    {}
  ],
  "value": {},
  "value_schema": {}
}

Build with us

Ready for your first call?

Early access is open. Tell us what you want your agents to do, and we will help you get your first key.

Talk to us Read the API guide