Reps: 7 operations (reps.list, reps.get, reps.excluded.list, reps.excluded.add, reps.excluded.remove, reps.setter_mode.get, reps.setter_mode.set).
GET /v1/reps
List the workspace's connected reps with their health and setter mode.
Only live (not archived) reps, oldest connected first. A key restricted to reps lists only those reps.
Operation id reps.listScopes reps:readRate class `read` Idempotency Not applicable Keys Developer keys Reps A key restricted to reps sees only data of its own reps
Field Type Required Description dataobject[]yes
Every operation can also answer the shared errors : authentication, scopes, rate limits and validation.
bash Copy
curl "https://api.dmhero.ai/v1/reps" \
-H "Authorization: Bearer $DMHERO_API_KEY"JSON Schema Response 200 Copy
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"ig_username": {
"type": "string"
},
"full_name": {
"type": [
"string",
"null"
]
},
"profile_pic_url": {
"type": [
"string",
"null"
]
},
"followers_count": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"health": {
"type": "object",
"properties": {
"token": {
"type": "string",
"enum": [
"ok",
"expired",
"rejected",
"missing"
]
},
"token_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
{
"type": "null"
}
]
},
"extension": {
"type": "string",
"enum": [
"online",
"paused",
"offline",
"never"
]
},
"extension_last_seen_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
{
"type": "null"
}
]
},
"extension_pause_code": {
"type": [
"string",
"null"
]
},
"dm_count_current_period": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"dm_cap_current_period": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"rate_limited_until": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
{
"type": "null"
}
]
}
},
"required": [
"token",
"token_expires_at",
"extension",
"extension_last_seen_at",
"extension_pause_code",
"dm_count_current_period",
"dm_cap_current_period",
"rate_limited_until"
],
"additionalProperties": false
},
"setter_mode": {
"anyOf": [
{
"type": "object",
"properties": {
"outbound": {
"type": "string",
"enum": [
"off",
"suggest",
"auto"
]
},
"inbound": {
"type": "string",
"enum": [
"off",
"suggest",
"auto"
]
}
},
"required": [
"outbound",
"inbound"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Null when the plan does not include the AI Setter."
},
"connected_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"required": [
"id",
"ig_username",
"full_name",
"profile_pic_url",
"followers_count",
"health",
"setter_mode",
"connected_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}GET /v1/reps/{rep_id}
Read one rep with its health and setter mode.
Operation id reps.getScopes reps:readRate class `read` Idempotency Not applicable Keys Developer keys Reps A key restricted to reps sees only data of its own reps
Name Type Required Description rep_idstringyes
Field Type Required Description connected_atdate-timeyes followers_countinteger | nullyes full_namestring | nullyes healthobjectyes iduuidyes ig_usernamestringyes profile_pic_urlstring | nullyes setter_modeobject | nullyes Null when the plan does not include the AI Setter.
Status Code When 404 `REP_NOT_FOUND_404` The rep does not exist in this workspace, is archived, or is outside the key's rep restriction.
Every operation can also answer the shared errors : authentication, scopes, rate limits and validation.
bash Copy
curl "https://api.dmhero.ai/v1/reps/string" \
-H "Authorization: Bearer $DMHERO_API_KEY"JSON Schema Response 200 Copy
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"ig_username": {
"type": "string"
},
"full_name": {
"type": [
"string",
"null"
]
},
"profile_pic_url": {
"type": [
"string",
"null"
]
},
"followers_count": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"health": {
"type": "object",
"properties": {
"token": {
"type": "string",
"enum": [
"ok",
"expired",
"rejected",
"missing"
]
},
"token_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
{
"type": "null"
}
]
},
"extension": {
"type": "string",
"enum": [
"online",
"paused",
"offline",
"never"
]
},
"extension_last_seen_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
{
"type": "null"
}
]
},
"extension_pause_code": {
"type": [
"string",
"null"
]
},
"dm_count_current_period": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"dm_cap_current_period": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"rate_limited_until": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
{
"type": "null"
}
]
}
},
"required": [
"token",
"token_expires_at",
"extension",
"extension_last_seen_at",
"extension_pause_code",
"dm_count_current_period",
"dm_cap_current_period",
"rate_limited_until"
],
"additionalProperties": false
},
"setter_mode": {
"anyOf": [
{
"type": "object",
"properties": {
"outbound": {
"type": "string",
"enum": [
"off",
"suggest",
"auto"
]
},
"inbound": {
"type": "string",
"enum": [
"off",
"suggest",
"auto"
]
}
},
"required": [
"outbound",
"inbound"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Null when the plan does not include the AI Setter."
},
"connected_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"required": [
"id",
"ig_username",
"full_name",
"profile_pic_url",
"followers_count",
"health",
"setter_mode",
"connected_at"
],
"additionalProperties": false
}GET /v1/reps/{rep_id}/excluded-handles
List the handles a rep's inbound setter never engages and never adds to the CRM.
Operation id reps.excluded.listScopes reps:readRate class `read` Idempotency Not applicable Keys Developer keys Reps A key restricted to reps sees only data of its own reps
Name Type Required Description rep_idstringyes
Field Type Required Description datastring[]yes Normalized handles: trimmed, no leading @, lowercase, in alphabetical order.
Status Code When 404 `REP_NOT_FOUND_404` The rep does not exist in this workspace, is archived, or is outside the key's rep restriction.
Every operation can also answer the shared errors : authentication, scopes, rate limits and validation.
bash Copy
curl "https://api.dmhero.ai/v1/reps/string/excluded-handles" \
-H "Authorization: Bearer $DMHERO_API_KEY"JSON Schema Response 200 Copy
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
},
"description": "Normalized handles: trimmed, no leading @, lowercase, in alphabetical order."
}
},
"required": [
"data"
],
"additionalProperties": false
}POST /v1/reps/{rep_id}/excluded-handles
Add handles to a rep's inbound exclusion list.
Each item is one handle. Handles are normalized (trimmed, leading @ dropped, lowercased) and deduplicated; one already on the list is a no-op. An item that still holds whitespace or a comma after trimming is refused (400, naming handles.<index>). added counts the handles that were not on it before.
Operation id reps.excluded.addScopes reps:writeRate class `write` Idempotency `Idempotency-Key` accepted Keys Developer keys Reps A key restricted to reps sees only data of its own reps
Name Type Required Description rep_idstringyes
Field Type Required Description handlesstring[]yes 1 to 500 items
Field Type Required Description addedintegeryes -9007199254740991 to 9007199254740991 datastring[]yes Normalized handles: trimmed, no leading @, lowercase, in alphabetical order. rep_iduuidyes
Every operation can also answer the shared errors : authentication, scopes, rate limits and validation.
bash Copy
curl -X POST "https://api.dmhero.ai/v1/reps/string/excluded-handles" \
-H "Authorization: Bearer $DMHERO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"handles": [
"string"
]
}'JSON Schema Request body Copy
{
"type": "object",
"properties": {
"handles": {
"minItems": 1,
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
}
},
"required": [
"handles"
]
}Response 200 Copy
{
"type": "object",
"properties": {
"rep_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"added": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"data": {
"type": "array",
"items": {
"type": "string"
},
"description": "Normalized handles: trimmed, no leading @, lowercase, in alphabetical order."
}
},
"required": [
"rep_id",
"added",
"data"
],
"additionalProperties": false
}DELETE /v1/reps/{rep_id}/excluded-handles/{handle}
Remove one handle from a rep's inbound exclusion list.
Operation id reps.excluded.removeScopes reps:writeRate class `write` Idempotency Not applicable Keys Developer keys Reps A key restricted to reps sees only data of its own reps
Name Type Required Description rep_idstringyes handlestringyes 1 to 100 characters
No body.
Every operation can also answer the shared errors : authentication, scopes, rate limits and validation.
bash Copy
curl -X DELETE "https://api.dmhero.ai/v1/reps/string/excluded-handles/string" \
-H "Authorization: Bearer $DMHERO_API_KEY"GET /v1/reps/{rep_id}/setter-mode
Read a rep's AI Setter mode for outbound replies and for inbound DMs.
Operation id reps.setter_mode.getScopes reps:readRate class `read` Idempotency Not applicable Keys Developer keys Reps A key restricted to reps sees only data of its own reps
Name Type Required Description rep_idstringyes
Field Type Required Description inbound"off" | "suggest" | "auto"yes outbound"off" | "suggest" | "auto"yes
Status Code When 404 `REP_NOT_FOUND_404` The rep does not exist in this workspace, is archived, or is outside the key's rep restriction.
Every operation can also answer the shared errors : authentication, scopes, rate limits and validation.
bash Copy
curl "https://api.dmhero.ai/v1/reps/string/setter-mode" \
-H "Authorization: Bearer $DMHERO_API_KEY"JSON Schema Response 200 Copy
{
"type": "object",
"properties": {
"outbound": {
"type": "string",
"enum": [
"off",
"suggest",
"auto"
]
},
"inbound": {
"type": "string",
"enum": [
"off",
"suggest",
"auto"
]
}
},
"required": [
"outbound",
"inbound"
],
"additionalProperties": false
}PUT /v1/reps/{rep_id}/setter-mode
Set a rep's AI Setter mode for outbound replies, inbound DMs, or both.
auto lets the setter reply on its own through the Meta API. At least one of outbound and inbound is required; the other keeps its value. Every change is written to the audit log.
Operation id reps.setter_mode.setScopes reps:writeRate class `write` Idempotency Not applicable Keys Developer keys Reps A key restricted to reps sees only data of its own reps
Name Type Required Description rep_idstringyes
Field Type Required Description inbound"off" | "suggest" | "auto"no outbound"off" | "suggest" | "auto"no
Field Type Required Description inbound"off" | "suggest" | "auto"yes outbound"off" | "suggest" | "auto"yes
Every operation can also answer the shared errors : authentication, scopes, rate limits and validation.
bash Copy
curl -X PUT "https://api.dmhero.ai/v1/reps/string/setter-mode" \
-H "Authorization: Bearer $DMHERO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"outbound": "off",
"inbound": "off"
}'JSON Schema Request body Copy
{
"type": "object",
"properties": {
"outbound": {
"type": "string",
"enum": [
"off",
"suggest",
"auto"
]
},
"inbound": {
"type": "string",
"enum": [
"off",
"suggest",
"auto"
]
}
}
}Response 200 Copy
{
"type": "object",
"properties": {
"outbound": {
"type": "string",
"enum": [
"off",
"suggest",
"auto"
]
},
"inbound": {
"type": "string",
"enum": [
"off",
"suggest",
"auto"
]
}
},
"required": [
"outbound",
"inbound"
],
"additionalProperties": false
}