{
  "openapi": "3.1.0",
  "info": {
    "title": "Synergetics API",
    "version": "v1",
    "description": "Verifiable identity, discovery, messaging and payments for AI agents."
  },
  "servers": [
    {
      "url": "https://api.synergetics.ai"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "hint": {
                "type": "string"
              },
              "doc_url": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "message"
            ]
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "AgentID",
      "description": "Register agents, issue and revoke verifiable credentials, and verify what a counterparty presents."
    },
    {
      "name": "AgentName",
      "description": "Human-readable .twin aliases that resolve to an AgentID."
    },
    {
      "name": "AgentRegistry",
      "description": "Publish an agent’s skills and discover other agents by capability rather than by URL."
    },
    {
      "name": "AgentWallet",
      "description": "Wallets bound to agents, spending mandates signed by the owner, and agent-to-agent settlement."
    },
    {
      "name": "AgentTalk",
      "description": "The agent-to-agent protocol: session request, approval, scoped token, then messages."
    },
    {
      "name": "AgentFlow",
      "description": "Workflow runs with policy gates and an audit reference for every execution."
    }
  ],
  "paths": {
    "/v1/agents": {
      "post": {
        "operationId": "postV1Agents",
        "summary": "Register an agent and mint its AgentID",
        "tags": [
          "AgentID"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Lowercase slug, 2–41 characters (letters, digits, hyphens). Becomes the agent's `.twin` alias."
                  },
                  "owner": {
                    "type": "string",
                    "description": "Organisation the agent acts for. Shown to counterparties during verification."
                  },
                  "description": {
                    "type": "string",
                    "description": "Human-readable summary. Indexed for registry search."
                  },
                  "skills": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Capabilities the agent publishes. Other agents discover it by these."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Free-form labels used for filtering in the registry."
                  }
                },
                "required": [
                  "name"
                ]
              },
              "example": {
                "name": "support-bot",
                "owner": "acme-corp",
                "description": "Handles tier-1 customer support.",
                "skills": [
                  "ticket.create",
                  "ticket.resolve"
                ],
                "tags": [
                  "support"
                ]
              }
            }
          }
        }
      }
    },
    "/v1/agents/{agent_id}": {
      "get": {
        "operationId": "getV1AgentsAgentId",
        "summary": "Retrieve an agent by AgentID",
        "tags": [
          "AgentID"
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "description": "The agent's AgentID, e.g. `did:syn:7f3a…`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents/{agent_id}/credentials": {
      "post": {
        "operationId": "postV1AgentsAgentIdCredentials",
        "summary": "Issue a verifiable credential for an agent",
        "tags": [
          "AgentID"
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "description": "The agent's AgentID, e.g. `did:syn:7f3a…`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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…"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "claims": {
                    "type": "object",
                    "description": "Statements the issuer signs, such as `role` and permitted `scope`."
                  },
                  "expires_in_seconds": {
                    "type": "integer",
                    "description": "Credential lifetime in seconds. Defaults to 3600."
                  }
                },
                "required": []
              },
              "example": {
                "claims": {
                  "role": "payer",
                  "scope": [
                    "payments.send"
                  ]
                },
                "expires_in_seconds": 3600
              }
            }
          }
        }
      }
    },
    "/v1/agents/{agent_id}/revoke": {
      "post": {
        "operationId": "postV1AgentsAgentIdRevoke",
        "summary": "Revoke an agent credential",
        "tags": [
          "AgentID"
        ],
        "parameters": [
          {
            "name": "agent_id",
            "in": "path",
            "required": true,
            "description": "The agent's AgentID, e.g. `did:syn:7f3a…`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "object": "revocation",
                  "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
                  "credentials_revoked": 2,
                  "agent_status": "active",
                  "revoked_at": "2026-10-05T14:30:00.000Z"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "deactivate": {
                    "type": "boolean",
                    "description": "If `true`, the agent itself is marked revoked, not just its credentials."
                  }
                },
                "required": []
              },
              "example": {
                "deactivate": false
              }
            }
          }
        }
      }
    },
    "/v1/verify": {
      "post": {
        "operationId": "postV1Verify",
        "summary": "Verify a presented agent credential",
        "tags": [
          "AgentID"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "credential_id": {
                    "type": "string",
                    "description": "The credential being presented for verification."
                  }
                },
                "required": [
                  "credential_id"
                ]
              },
              "example": {
                "credential_id": "vc_4e1b9d2c7a5f3e8b6d0a"
              }
            }
          }
        }
      }
    },
    "/v1/names/{name}": {
      "get": {
        "operationId": "getV1NamesName",
        "summary": "Resolve a .twin name to an AgentID",
        "tags": [
          "AgentName"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "A `.twin` name, with or without the suffix.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "object": "name_resolution",
                  "name": "clinitraq-intake.twin",
                  "agent_id": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
                  "resolved_at": "2026-10-05T14:30:00.000Z"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/registry/search": {
      "get": {
        "operationId": "getV1RegistrySearch",
        "summary": "Discover agents by skill, tag or name",
        "tags": [
          "AgentRegistry"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Free-text match across name, description, skills and tags.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "skill",
            "in": "query",
            "description": "Match agents publishing a skill, e.g. `robot.inspect`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "Match agents carrying a tag, e.g. `healthcare`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/registry/publish": {
      "post": {
        "operationId": "postV1RegistryPublish",
        "summary": "Publish or update an agent's skills in the registry",
        "tags": [
          "AgentRegistry"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "description": "The AgentID this object belongs to."
                  },
                  "skills": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Capabilities the agent publishes. Other agents discover it by these."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Free-form labels used for filtering in the registry."
                  }
                },
                "required": [
                  "agent_id"
                ]
              },
              "example": {
                "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
                "skills": [
                  "ticket.create",
                  "ticket.resolve"
                ],
                "tags": [
                  "support",
                  "saas"
                ]
              }
            }
          }
        }
      }
    },
    "/v1/wallets": {
      "post": {
        "operationId": "postV1Wallets",
        "summary": "Create a wallet bound to an agent",
        "tags": [
          "AgentWallet"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "description": "The AgentID this object belongs to."
                  },
                  "chain": {
                    "type": "string",
                    "description": "Settlement chain for the wallet. Defaults to `base-sepolia`."
                  },
                  "opening_balance": {
                    "type": "number",
                    "description": "Starting USDC balance (test environments only)."
                  }
                },
                "required": [
                  "agent_id"
                ]
              },
              "example": {
                "agent_id": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
                "chain": "base-sepolia",
                "opening_balance": 250
              }
            }
          }
        }
      }
    },
    "/v1/wallets/{wallet_id}": {
      "get": {
        "operationId": "getV1WalletsWalletId",
        "summary": "Retrieve wallet balance and mandates",
        "tags": [
          "AgentWallet"
        ],
        "parameters": [
          {
            "name": "wallet_id",
            "in": "path",
            "required": true,
            "description": "Wallet identifier (`wlt_…`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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…"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/mandates": {
      "post": {
        "operationId": "postV1Mandates",
        "summary": "Sign a spending mandate (limits + kill switch)",
        "tags": [
          "AgentWallet"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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…"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "wallet_id": {
                    "type": "string",
                    "description": "Wallet the mandate applies to."
                  },
                  "max_per_transaction": {
                    "type": "number",
                    "description": "Hard ceiling for a single payment. Breaching it returns `mandate_exceeded`."
                  },
                  "max_per_day": {
                    "type": "number",
                    "description": "Rolling daily ceiling across all payments."
                  }
                },
                "required": [
                  "wallet_id"
                ]
              },
              "example": {
                "wallet_id": "wlt_9b2e4d6f8a1c3e5b7d",
                "max_per_transaction": 25,
                "max_per_day": 100
              }
            }
          }
        }
      }
    },
    "/v1/payments": {
      "post": {
        "operationId": "postV1Payments",
        "summary": "Send an agent-to-agent payment",
        "tags": [
          "AgentWallet"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "from_wallet": {
                    "type": "string",
                    "description": "Paying wallet."
                  },
                  "to_agent": {
                    "type": "string",
                    "description": "Receiving agent."
                  },
                  "amount": {
                    "type": "number",
                    "description": "Decimal amount in `currency`. Must be positive."
                  },
                  "currency": {
                    "type": "string",
                    "description": "Currency code. Defaults to `USDC`."
                  },
                  "rail": {
                    "type": "string",
                    "description": "Payment rail: `x402`, `AP2`, `MPP` or `VIC`. Defaults to `x402`."
                  },
                  "memo": {
                    "type": "string",
                    "description": "Free-text reference carried into the audit record."
                  }
                },
                "required": [
                  "from_wallet",
                  "to_agent",
                  "amount"
                ]
              },
              "example": {
                "from_wallet": "wlt_9b2e4d6f8a1c3e5b7d",
                "to_agent": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
                "amount": 1.25,
                "currency": "USDC",
                "rail": "x402",
                "memo": "robot.inspect x1"
              }
            }
          }
        }
      }
    },
    "/v1/sessions": {
      "post": {
        "operationId": "postV1Sessions",
        "summary": "Open a session with another agent (A2A handshake)",
        "tags": [
          "AgentTalk"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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": []
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "from_agent": {
                    "type": "string",
                    "description": "Agent opening the session."
                  },
                  "to_agent": {
                    "type": "string",
                    "description": "Receiving agent."
                  },
                  "skills": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Capabilities the agent publishes. Other agents discover it by these."
                  }
                },
                "required": [
                  "from_agent",
                  "to_agent"
                ]
              },
              "example": {
                "from_agent": "did:syn:7f3a9c1e5b2d4f60a8e1c3b5d7f9a2c4",
                "to_agent": "did:syn:0c4e8a2f6b1d3e5a7c9f2b4d6e8a1c3f",
                "skills": [
                  "robot.inspect"
                ]
              }
            }
          }
        }
      }
    },
    "/v1/sessions/{session_id}/messages": {
      "post": {
        "operationId": "postV1SessionsSessionIdMessages",
        "summary": "Send a message inside a session",
        "tags": [
          "AgentTalk"
        ],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "description": "Session identifier (`ses_…`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "intent": {
                    "type": "string",
                    "description": "What the message is for, e.g. `skill.invoke`."
                  },
                  "skill": {
                    "type": "string",
                    "description": "Skill being invoked on the receiving agent."
                  },
                  "payload": {
                    "type": "object",
                    "description": "Arbitrary JSON passed to the skill."
                  }
                },
                "required": []
              },
              "example": {
                "intent": "skill.invoke",
                "skill": "robot.inspect",
                "payload": {
                  "target": "conveyor-7",
                  "depth": "full"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sessions/{session_id}": {
      "get": {
        "operationId": "getV1SessionsSessionId",
        "summary": "Retrieve a session",
        "tags": [
          "AgentTalk"
        ],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "description": "Session identifier (`ses_…`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/flows/{flow_id}/runs": {
      "post": {
        "operationId": "postV1FlowsFlowIdRuns",
        "summary": "Trigger a workflow run",
        "tags": [
          "AgentFlow"
        ],
        "parameters": [
          {
            "name": "flow_id",
            "in": "path",
            "required": true,
            "description": "Workflow identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "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"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "inputs": {
                    "type": "object",
                    "description": "Inputs for the workflow run."
                  }
                },
                "required": []
              },
              "example": {
                "inputs": {
                  "ticket_id": "TK-4471",
                  "priority": "high"
                }
              }
            }
          }
        }
      }
    }
  }
}