API reference · Synergetics Developers

API reference

The Synergetics API is organised around REST. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP status codes and bearer authentication.

Prefer a machine-readable spec? Download openapi.json (OpenAPI 3.1) to generate clients or import into Postman and Insomnia.

#Base URL

Base URL

https://api.synergetics.ai/v1

Every request needs an API key in the Authorization header. See Authentication.

#Conventions

Topic	Behaviour
Identifiers	`did:syn:<hex>` for agents; prefixed opaque ids elsewhere (`vc_`, `wlt_`, `mnd_`, `ses_`, `pay_`). See identifiers.
Errors	Non-2xx responses carry an `error` object with a stable `type`. See Errors.
Lists	Return `{ "object": "list", "data": [...], "has_more": false, "total": 0 }`.
Time	All timestamps are ISO 8601 in UTC.
Money	Decimal amounts with an explicit `currency`. No implicit minor units.
Versioning	The major version is in the path (`/v1`). Additive changes ship without a version bump and are listed in the changelog.

#Endpoints

POST/v1/agents GET/v1/agents/{agent_id}POST/v1/agents/{agent_id}/credentials POST/v1/agents/{agent_id}/revoke POST/v1/verify GET/v1/names/{name}GET/v1/registry/search POST/v1/registry/publish POST/v1/wallets GET/v1/wallets/{wallet_id}POST/v1/mandates POST/v1/payments POST/v1/sessions POST/v1/sessions/{session_id}/messages GET/v1/sessions/{session_id}POST/v1/flows/{flow_id}/runs

#AgentID

#Register an agent and mint its AgentID

POST/v1/agents

Returns an agent object if the call succeeded, and an error otherwise.

Body parameters

namestringrequired
Lowercase slug, 2–41 characters (letters, digits, hyphens). Becomes the agent's .twin alias.
ownerstring
Organisation the agent acts for. Shown to counterparties during verification.
descriptionstring
Human-readable summary. Indexed for registry search.
skillsstring[]
Capabilities the agent publishes. Other agents discover it by these.
tagsstring[]
Free-form labels used for filtering in the registry.

Errors

missing_parameter invalid_parameter

curl -X POST https://api.synergetics.ai/v1/agents \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-bot",
    "owner": "acme-corp",
    "description": "Handles tier-1 customer support.",
    "skills": [
      "ticket.create",
      "ticket.resolve"
    ],
    "tags": [
      "support"
    ]
  }'

import os
import requests

res = requests.post(
    "https://api.synergetics.ai/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
    json={
        "name": "support-bot",
        "owner": "acme-corp",
        "description": "Handles tier-1 customer support.",
        "skills": [
            "ticket.create",
            "ticket.resolve"
        ],
        "tags": [
            "support"
        ]
    },
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "support-bot",
    "owner": "acme-corp",
    "description": "Handles tier-1 customer support.",
    "skills": [
      "ticket.create",
      "ticket.resolve"
    ],
    "tags": [
      "support"
    ]
  }),
});
console.log(await res.json());

Response · 200

{
  "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
  "object": "agent",
  "name": "support-bot",
  "twin_name": "support-bot.twin",
  "owner": "acme-corp",
  "description": "Handles tier-1 customer support.",
  "skills": [
    "ticket.create",
    "ticket.resolve"
  ],
  "tags": [
    "support"
  ],
  "kya_status": "verified",
  "status": "active",
  "created": "2026-10-05T14:30:00.000Z"
}

#Retrieve an agent by AgentID

GET/v1/agents/{agent_id}

Returns an agent object if the call succeeded, and an error otherwise.

Path parameters

agent_idstringrequired
The agent's AgentID, e.g. did:syn:7f3a….

Errors

agent_not_found

curl https://api.synergetics.ai/v1/agents/did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4 \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY"

import os
import requests

res = requests.get(
    "https://api.synergetics.ai/v1/agents/did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/agents/did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
  },
});
console.log(await res.json());

Response · 200

{
  "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
  "object": "agent",
  "name": "support-bot",
  "twin_name": "support-bot.twin",
  "owner": "acme-corp",
  "description": "Handles tier-1 customer support.",
  "skills": [
    "ticket.create",
    "ticket.resolve"
  ],
  "tags": [
    "support",
    "saas"
  ],
  "kya_status": "verified",
  "status": "active",
  "created": "2026-10-05T14:30:00.000Z",
  "published_at": "2026-10-05T14:30:00.000Z"
}

#Issue a verifiable credential for an agent

POST/v1/agents/{agent_id}/credentials

Returns a credential object if the call succeeded, and an error otherwise.

Path parameters

agent_idstringrequired
The agent's AgentID, e.g. did:syn:7f3a….

Body parameters

claimsobject
Statements the issuer signs, such as role and permitted scope.
expires_in_secondsinteger
Credential lifetime in seconds. Defaults to 3600.

Errors

agent_not_found

curl -X POST https://api.synergetics.ai/v1/agents/did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4/credentials \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "claims": {
      "role": "payer",
      "scope": [
        "payments.send"
      ]
    },
    "expires_in_seconds": 3600
  }'

import os
import requests

res = requests.post(
    "https://api.synergetics.ai/v1/agents/did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4/credentials",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
    json={
        "claims": {
            "role": "payer",
            "scope": [
                "payments.send"
            ]
        },
        "expires_in_seconds": 3600
    },
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/agents/did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4/credentials", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "claims": {
      "role": "payer",
      "scope": [
        "payments.send"
      ]
    },
    "expires_in_seconds": 3600
  }),
});
console.log(await res.json());

Response · 200

{
  "object": "credential",
  "credential_id": "vc_4e1b9d2c7a5f3e8b6d0a",
  "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
  "issuer": "did:syn:issuer:synergetics",
  "claims": {
    "role": "payer",
    "scope": [
      "payments.send"
    ]
  },
  "issued_at": "2026-10-05T14:30:00.000Z",
  "expires_at": "2026-10-05T14:30:00.000Z",
  "status": "revoked",
  "signature": {
    "alg": "ES256",
    "value": "MEUCIQDx3c…"
  }
}

#Revoke an agent credential

POST/v1/agents/{agent_id}/revoke

Returns a revocation object if the call succeeded, and an error otherwise.

Path parameters

agent_idstringrequired
The agent's AgentID, e.g. did:syn:7f3a….

Body parameters

deactivateboolean
If true, the agent itself is marked revoked, not just its credentials.

Errors

agent_not_found

curl -X POST https://api.synergetics.ai/v1/agents/did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4/revoke \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deactivate": false
  }'

import os
import requests

res = requests.post(
    "https://api.synergetics.ai/v1/agents/did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4/revoke",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
    json={
        "deactivate": False
    },
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/agents/did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4/revoke", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "deactivate": false
  }),
});
console.log(await res.json());

Response · 200

{
  "object": "revocation",
  "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
  "credentials_revoked": 2,
  "agent_status": "active",
  "revoked_at": "2026-10-05T14:30:00.000Z"
}

#Verify a presented agent credential

POST/v1/verify

Returns a verification object if the call succeeded, and an error otherwise.

Body parameters

credential_idstringrequired
The credential being presented for verification.

Errors

credential_not_found

curl -X POST https://api.synergetics.ai/v1/verify \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_id": "vc_4e1b9d2c7a5f3e8b6d0a"
  }'

import os
import requests

res = requests.post(
    "https://api.synergetics.ai/v1/verify",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
    json={
        "credential_id": "vc_4e1b9d2c7a5f3e8b6d0a"
    },
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "credential_id": "vc_4e1b9d2c7a5f3e8b6d0a"
  }),
});
console.log(await res.json());

Response · 200

{
  "object": "verification",
  "verified": true,
  "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
  "credential_id": "vc_4e1b9d2c7a5f3e8b6d0a",
  "issuer": "did:syn:issuer:synergetics",
  "signature_valid": true,
  "checks": {
    "signature": "pass",
    "issuer_trusted": "pass",
    "not_revoked": "pass",
    "not_expired": "pass"
  },
  "verified_at": "2026-10-05T14:30:00.000Z"
}

#AgentName

Human-readable .twin aliases that resolve to an AgentID.

#Resolve a .twin name to an AgentID

GET/v1/names/{name}

Returns a name_resolution object if the call succeeded, and an error otherwise.

Path parameters

namestringrequired
A .twin name, with or without the suffix.

Errors

name_not_found

curl https://api.synergetics.ai/v1/names/clinitraq-intake.twin \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY"

import os
import requests

res = requests.get(
    "https://api.synergetics.ai/v1/names/clinitraq-intake.twin",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/names/clinitraq-intake.twin", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
  },
});
console.log(await res.json());

Response · 200

{
  "object": "name_resolution",
  "name": "clinitraq-intake.twin",
  "agent_id": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
  "resolved_at": "2026-10-05T14:30:00.000Z"
}

#AgentRegistry

Publish an agent’s skills and discover other agents by capability rather than by URL.

#Discover agents by skill, tag or name

GET/v1/registry/search

Returns a list of matching objects. An empty search returns an empty data array, not an error.

Query parameters

qstring
Free-text match across name, description, skills and tags.
skillstring
Match agents publishing a skill, e.g. robot.inspect.
tagstring
Match agents carrying a tag, e.g. healthcare.

curl "https://api.synergetics.ai/v1/registry/search?skill=robot.inspect" \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY"

import os
import requests

res = requests.get(
    "https://api.synergetics.ai/v1/registry/search?skill=robot.inspect",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/registry/search?skill=robot.inspect", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
  },
});
console.log(await res.json());

Response · 200

{
  "object": "list",
  "data": [
    {
      "agent_id": "did:syn:5d2a8f4c1e7b3a9d6c0e2f8b4a1d7e3c",
      "name": "apollo-sim",
      "twin_name": "apollo-sim.twin",
      "owner": "Synergetics Labs",
      "skills": [
        "robot.move",
        "robot.inspect",
        "robot.status"
      ],
      "tags": [
        "physical-ai",
        "simulation",
        "machine-economy"
      ],
      "kya_status": "verified"
    }
  ],
  "has_more": false,
  "total": 1
}

#Publish or update an agent's skills in the registry

POST/v1/registry/publish

Returns a registry_entry object if the call succeeded, and an error otherwise.

Body parameters

agent_idstringrequired
The AgentID this object belongs to.
skillsstring[]
Capabilities the agent publishes. Other agents discover it by these.
tagsstring[]
Free-form labels used for filtering in the registry.

Errors

agent_not_found

curl -X POST https://api.synergetics.ai/v1/registry/publish \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
    "skills": [
      "ticket.create",
      "ticket.resolve"
    ],
    "tags": [
      "support",
      "saas"
    ]
  }'

import os
import requests

res = requests.post(
    "https://api.synergetics.ai/v1/registry/publish",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
    json={
        "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
        "skills": [
            "ticket.create",
            "ticket.resolve"
        ],
        "tags": [
            "support",
            "saas"
        ]
    },
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/registry/publish", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
    "skills": [
      "ticket.create",
      "ticket.resolve"
    ],
    "tags": [
      "support",
      "saas"
    ]
  }),
});
console.log(await res.json());

Response · 200

{
  "object": "registry_entry",
  "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
  "name": "support-bot",
  "skills": [
    "ticket.create",
    "ticket.resolve"
  ],
  "tags": [
    "support",
    "saas"
  ],
  "discoverable": true,
  "published_at": "2026-10-05T14:30:00.000Z"
}

#AgentWallet

Wallets bound to agents, spending mandates signed by the owner, and agent-to-agent settlement.

#Create a wallet bound to an agent

POST/v1/wallets

Returns a wallet object if the call succeeded, and an error otherwise.

Body parameters

agent_idstringrequired
The AgentID this object belongs to.
chainstring
Settlement chain for the wallet. Defaults to base-sepolia.
opening_balancenumber
Starting USDC balance (test environments only).

Errors

agent_not_found

curl -X POST https://api.synergetics.ai/v1/wallets \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
    "chain": "base-sepolia",
    "opening_balance": 250
  }'

import os
import requests

res = requests.post(
    "https://api.synergetics.ai/v1/wallets",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
    json={
        "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
        "chain": "base-sepolia",
        "opening_balance": 250
    },
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/wallets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
    "chain": "base-sepolia",
    "opening_balance": 250
  }),
});
console.log(await res.json());

Response · 200

{
  "object": "wallet",
  "wallet_id": "wlt_9b2e4d6f8a1c3e5b7d",
  "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
  "chain": "base-sepolia",
  "address": "0xa1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4",
  "balances": {
    "USDC": 250
  },
  "key_custody": "customer_hsm",
  "created": "2026-10-05T14:30:00.000Z"
}

#Retrieve wallet balance and mandates

GET/v1/wallets/{wallet_id}

Returns a wallet object if the call succeeded, and an error otherwise.

Path parameters

wallet_idstringrequired
Wallet identifier (wlt_…).

Errors

wallet_not_found

curl https://api.synergetics.ai/v1/wallets/wlt_9b2e4d6f8a1c3e5b7d \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY"

import os
import requests

res = requests.get(
    "https://api.synergetics.ai/v1/wallets/wlt_9b2e4d6f8a1c3e5b7d",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/wallets/wlt_9b2e4d6f8a1c3e5b7d", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
  },
});
console.log(await res.json());

Response · 200

{
  "object": "wallet",
  "wallet_id": "wlt_9b2e4d6f8a1c3e5b7d",
  "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
  "chain": "base-sepolia",
  "address": "0xa1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4",
  "balances": {
    "USDC": 248.75
  },
  "key_custody": "customer_hsm",
  "created": "2026-10-05T14:30:00.000Z",
  "mandate": {
    "object": "mandate",
    "mandate_id": "mnd_5c8e1f3a9d2b",
    "wallet_id": "wlt_9b2e4d6f8a1c3e5b7d",
    "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
    "max_per_transaction": 25,
    "max_per_day": 100,
    "allowed_counterparties": "any_verified",
    "kill_switch": "armed",
    "signed_by": "did:syn:owner:acme-corp",
    "created": "2026-10-05T14:30:00.000Z",
    "signature": {
      "alg": "ES256",
      "value": "MEUCIQDx3c…"
    }
  }
}

#Sign a spending mandate (limits + kill switch)

POST/v1/mandates

Returns a mandate object if the call succeeded, and an error otherwise.

Body parameters

wallet_idstringrequired
Wallet the mandate applies to.
max_per_transactionnumber
Hard ceiling for a single payment. Breaching it returns mandate_exceeded.
max_per_daynumber
Rolling daily ceiling across all payments.

Errors

wallet_not_found

curl -X POST https://api.synergetics.ai/v1/mandates \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": "wlt_9b2e4d6f8a1c3e5b7d",
    "max_per_transaction": 25,
    "max_per_day": 100
  }'

import os
import requests

res = requests.post(
    "https://api.synergetics.ai/v1/mandates",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
    json={
        "wallet_id": "wlt_9b2e4d6f8a1c3e5b7d",
        "max_per_transaction": 25,
        "max_per_day": 100
    },
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/mandates", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "wallet_id": "wlt_9b2e4d6f8a1c3e5b7d",
    "max_per_transaction": 25,
    "max_per_day": 100
  }),
});
console.log(await res.json());

Response · 200

{
  "object": "mandate",
  "mandate_id": "mnd_5c8e1f3a9d2b",
  "wallet_id": "wlt_9b2e4d6f8a1c3e5b7d",
  "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
  "max_per_transaction": 25,
  "max_per_day": 100,
  "allowed_counterparties": "any_verified",
  "kill_switch": "armed",
  "signed_by": "did:syn:owner:acme-corp",
  "created": "2026-10-05T14:30:00.000Z",
  "signature": {
    "alg": "ES256",
    "value": "MEUCIQDx3c…"
  }
}

#Send an agent-to-agent payment

POST/v1/payments

Returns a payment object if the call succeeded, and an error otherwise.

Body parameters

from_walletstringrequired
Paying wallet.
to_agentstringrequired
Receiving agent.
amountnumberrequired
Decimal amount in currency. Must be positive.
currencystring
Currency code. Defaults to USDC.
railstring
Payment rail: x402, AP2, MPP or VIC. Defaults to x402.
memostring
Free-text reference carried into the audit record.

Errors

wallet_not_found invalid_parameter mandate_exceeded insufficient_funds

curl -X POST https://api.synergetics.ai/v1/payments \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_wallet": "wlt_9b2e4d6f8a1c3e5b7d",
    "to_agent": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
    "amount": 1.25,
    "currency": "USDC",
    "rail": "x402",
    "memo": "robot.inspect x1"
  }'

import os
import requests

res = requests.post(
    "https://api.synergetics.ai/v1/payments",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
    json={
        "from_wallet": "wlt_9b2e4d6f8a1c3e5b7d",
        "to_agent": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
        "amount": 1.25,
        "currency": "USDC",
        "rail": "x402",
        "memo": "robot.inspect x1"
    },
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "from_wallet": "wlt_9b2e4d6f8a1c3e5b7d",
    "to_agent": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
    "amount": 1.25,
    "currency": "USDC",
    "rail": "x402",
    "memo": "robot.inspect x1"
  }),
});
console.log(await res.json());

Response · 200

{
  "object": "payment",
  "payment_id": "pay_5c8e1f3a9d2b",
  "from_wallet": "wlt_9b2e4d6f8a1c3e5b7d",
  "from_agent": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
  "to_agent": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
  "amount": 1.25,
  "currency": "USDC",
  "rail": "x402",
  "memo": "robot.inspect x1",
  "status": "settled",
  "settled_at": "2026-10-05T14:30:00.000Z",
  "tx_hash": "0xa1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4",
  "remaining_balance": 248.75
}

#AgentTalk

The agent-to-agent protocol: session request, approval, scoped token, then messages.

#Open a session with another agent (A2A handshake)

POST/v1/sessions

Returns a session object if the call succeeded, and an error otherwise.

Body parameters

from_agentstringrequired
Agent opening the session.
to_agentstringrequired
Receiving agent.
skillsstring[]
Capabilities the agent publishes. Other agents discover it by these.

Errors

agent_not_found

curl -X POST https://api.synergetics.ai/v1/sessions \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_agent": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
    "to_agent": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
    "skills": [
      "robot.inspect"
    ]
  }'

import os
import requests

res = requests.post(
    "https://api.synergetics.ai/v1/sessions",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
    json={
        "from_agent": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
        "to_agent": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
        "skills": [
            "robot.inspect"
        ]
    },
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "from_agent": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
    "to_agent": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
    "skills": [
      "robot.inspect"
    ]
  }),
});
console.log(await res.json());

Response · 200

{
  "object": "session",
  "session_id": "ses_2d4f6b8e1a3c5e7f9b2d",
  "from_agent": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
  "to_agent": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
  "requested_skills": [
    "robot.inspect"
  ],
  "status": "approved",
  "approval": {
    "mode": "auto",
    "policy": "both_parties_kya_verified",
    "approved_at": "2026-10-05T14:30:00.000Z"
  },
  "token": "st_5c8e1f3a9d2b",
  "protocol": "agenttalk/1.0",
  "compatible_with": [
    "google-a2a",
    "mcp-bridge"
  ],
  "expires_at": "2026-10-05T14:30:00.000Z",
  "messages": []
}

#Send a message inside a session

POST/v1/sessions/{session_id}/messages

Returns a message object if the call succeeded, and an error otherwise.

Path parameters

session_idstringrequired
Session identifier (ses_…).

Body parameters

intentstring
What the message is for, e.g. skill.invoke.
skillstring
Skill being invoked on the receiving agent.
payloadobject
Arbitrary JSON passed to the skill.

Errors

session_not_found session_expired

curl -X POST https://api.synergetics.ai/v1/sessions/ses_2d4f6b8e1a3c5e7f9b2d/messages \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "skill.invoke",
    "skill": "robot.inspect",
    "payload": {
      "target": "conveyor-7",
      "depth": "full"
    }
  }'

import os
import requests

res = requests.post(
    "https://api.synergetics.ai/v1/sessions/ses_2d4f6b8e1a3c5e7f9b2d/messages",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
    json={
        "intent": "skill.invoke",
        "skill": "robot.inspect",
        "payload": {
            "target": "conveyor-7",
            "depth": "full"
        }
    },
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/sessions/ses_2d4f6b8e1a3c5e7f9b2d/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "intent": "skill.invoke",
    "skill": "robot.inspect",
    "payload": {
      "target": "conveyor-7",
      "depth": "full"
    }
  }),
});
console.log(await res.json());

Response · 200

{
  "object": "message",
  "message_id": "msg_5c8e1f3a9d2b",
  "session_id": "ses_2d4f6b8e1a3c5e7f9b2d",
  "from_agent": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
  "to_agent": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
  "intent": "skill.invoke",
  "skill": "robot.inspect",
  "payload": {
    "target": "conveyor-7",
    "depth": "full"
  },
  "sent_at": "2026-10-05T14:30:00.000Z",
  "delivery": "encrypted",
  "result": {
    "status": "accepted",
    "receipt": "rcpt_5c8e1f3a9d2b"
  }
}

#Retrieve a session

GET/v1/sessions/{session_id}

Returns a session object if the call succeeded, and an error otherwise.

Path parameters

session_idstringrequired
Session identifier (ses_…).

Errors

session_not_found

curl https://api.synergetics.ai/v1/sessions/ses_2d4f6b8e1a3c5e7f9b2d \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY"

import os
import requests

res = requests.get(
    "https://api.synergetics.ai/v1/sessions/ses_2d4f6b8e1a3c5e7f9b2d",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/sessions/ses_2d4f6b8e1a3c5e7f9b2d", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
  },
});
console.log(await res.json());

Response · 200

{
  "object": "session",
  "session_id": "ses_2d4f6b8e1a3c5e7f9b2d",
  "from_agent": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
  "to_agent": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
  "requested_skills": [
    "robot.inspect"
  ],
  "status": "approved",
  "approval": {
    "mode": "auto",
    "policy": "both_parties_kya_verified",
    "approved_at": "2026-10-05T14:30:00.000Z"
  },
  "token": "st_5c8e1f3a9d2b",
  "protocol": "agenttalk/1.0",
  "compatible_with": [
    "google-a2a",
    "mcp-bridge"
  ],
  "expires_at": "2026-10-05T14:30:00.000Z",
  "messages": [
    "msg_5c8e1f3a9d2b"
  ]
}

#AgentFlow

Workflow runs with policy gates and an audit reference for every execution.

#Trigger a workflow run

POST/v1/flows/{flow_id}/runs

Returns a flow_run object if the call succeeded, and an error otherwise.

Path parameters

flow_idstringrequired
Workflow identifier.

Body parameters

inputsobject
Inputs for the workflow run.

curl -X POST https://api.synergetics.ai/v1/flows/flow_ticket_triage/runs \
  -H "Authorization: Bearer $SYNERGETICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "ticket_id": "TK-4471",
      "priority": "high"
    }
  }'

import os
import requests

res = requests.post(
    "https://api.synergetics.ai/v1/flows/flow_ticket_triage/runs",
    headers={"Authorization": f"Bearer {os.environ['SYNERGETICS_API_KEY']}"},
    json={
        "inputs": {
            "ticket_id": "TK-4471",
            "priority": "high"
        }
    },
)
res.raise_for_status()
print(res.json())

const res = await fetch("https://api.synergetics.ai/v1/flows/flow_ticket_triage/runs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYNERGETICS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "inputs": {
      "ticket_id": "TK-4471",
      "priority": "high"
    }
  }),
});
console.log(await res.json());

Response · 200

{
  "object": "flow_run",
  "run_id": "run_5c8e1f3a9d2b",
  "flow_id": "flow_ticket_triage",
  "status": "succeeded",
  "inputs": {
    "ticket_id": "TK-4471",
    "priority": "high"
  },
  "steps": [
    {
      "step": "read.inputs",
      "status": "succeeded",
      "duration_ms": 85
    },
    {
      "step": "agent.plan",
      "status": "succeeded",
      "duration_ms": 92
    },
    {
      "step": "policy.gate",
      "status": "succeeded",
      "duration_ms": 143
    },
    {
      "step": "agent.execute",
      "status": "succeeded",
      "duration_ms": 155
    },
    {
      "step": "record.audit",
      "status": "succeeded",
      "duration_ms": 210
    }
  ],
  "human_approvals": 0,
  "audit_ref": "aud_5c8e1f3a9d2b",
  "started_at": "2026-10-05T14:30:00.000Z",
  "finished_at": "2026-10-05T14:30:00.000Z"
}