POST /api/v1/interact

Enables interaction with a Zams AI agent to process messages, execute actions, and receive responses.

Authentication

Example Requests

cURL

curl --location '<https://api.zams.com/api/v1/interact>' \\
--header 'accept: application/json' \\
--header 'X-API-Key: ********' \\
--header 'Content-Type: application/json' \\
--data '{
  "messages": [
    {
      "role": "user",
      "content": "Show me the last 5 emails in my inbox."
    }
  ],
  "agent_id": "63a9c4f2e08bd157291af46d825c09741b3e",
  "files": [
      {
        "id": "file-library-id-123",
        "name": "data.csv"
      }
  ],
  "actions": [
    "75b2c8d4a6f931e0572849c63b1a50d7e94c28f5"
  ]
}'

Python

import requests
import json

def interact_with_agent(agent_id, messages, actions):
    url = "<https://api.zams.com/api/v1/interact>"
    
    headers = {
        "accept": "application/json",
        "X-API-Key": "********",
        "Content-Type": "application/json"
    }
    
    payload = {
        "messages": messages,
        "agent_id": agent_id,
        "actions": actions
    }
    
    response = requests.post(url, headers=headers, json=payload)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Error: {response.status_code}")

# Example usage
messages = [
    {
        "role": "user",
        "content": "show me the last 5 emails in my inbox"
    }
]

actions = [
    "75b2c8d4a6f931e0572849c63b1a50d7e94c28f5"
]

response = interact_with_agent("63a9c4f2e08bd157291af46d825c09741b3e", messages, actions)
print(response)

Request Body

Message Object Format

Example Response

{
  "response": "Here are the last 5 emails in your inbox:\\n\\n---\\n\\n&lt;b&gt;1. Subject:&lt;/b&gt; Re: [CompanyX/project-alpha] merge feature update (PR #42)  \\n&lt;b&gt;From:&lt;/b&gt; dev-team &lt;a href=\\"<mailto:[email protected]>\\"&gt;[email protected]&lt;/a&gt;  \\n&lt;b&gt;To:&lt;/b&gt; \\"CompanyX/project-alpha\\" &lt;a href=\\"<mailto:[email protected]>\\"&gt;[email protected]&lt;/a&gt;  \\n&lt;b&gt;Date:&lt;/b&gt; Mon, 23 Jun 2025 11:17:36 -0700  \\n&lt;b&gt;Snippet:&lt;/b&gt; @dev-team approved this pull request. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread...\\n\\n---\\n\\n&lt;b&gt;2. Subject:&lt;/b&gt; Order Confirmation - Delicious Eats - 06/24/2025 07:00 AM  \\n&lt;b&gt;From:&lt;/b&gt; Delicious Eats &lt;a href=\\"<mailto:[email protected]>\\"&gt;[email protected]&lt;/a&gt;  \\n&lt;b&gt;To:&lt;/b&gt; Jane Smith &lt;a href=\\"<mailto:[email protected]>\\"&gt;[email protected]&lt;/a&gt;  \\n&lt;b&gt;Date:&lt;/b&gt; Mon, 23 Jun 2025 18:06:55 +0000  \\n&lt;b&gt;Snippet:&lt;/b&gt; Hi Jane, Thanks for your breakfast order scheduled for 06/24/2025 07:00 AM. Any questions? Contact us at &lt;a href=\\"<mailto:[email protected]>\\"&gt;[email protected]&lt;/a&gt;...\\n\\n---\\n\\n&lt;b&gt;3. Subject:&lt;/b&gt; Team Lunch Reminder  \\n&lt;b&gt;From:&lt;/b&gt; Office Admin &lt;a href=\\"<mailto:[email protected]>\\"&gt;[email protected]&lt;/a&gt;  \\n&lt;b&gt;To:&lt;/b&gt; \\"&lt;a href=\\"<http://example.com/\\>"&gt;Example Team&lt;/a&gt;\\" &lt;a href=\\"<mailto:[email protected]>\\"&gt;[email protected]&lt;/a&gt;  \\n&lt;b&gt;Date:&lt;/b&gt; Mon, 23 Jun 2025 11:00:00 -0700  \\n&lt;b&gt;Snippet:&lt;/b&gt; Hello team, Reminder to submit your lunch preferences by 4 PM today. Tomorrow we'll have special options from Tasty Bites Catering including vegetarian and gluten-free choices...\\n\\n---\\n\\n&lt;b&gt;4. Subject:&lt;/b&gt; Jane, interested in our services?  \\n&lt;b&gt;From:&lt;/b&gt; Marketing Team &lt;a href=\\"<mailto:[email protected]>\\"&gt;[email protected]&lt;/a&gt;  \\n&lt;b&gt;To:&lt;/b&gt; &lt;a href=\\"<mailto:[email protected]>\\"&gt;[email protected]&lt;/a&gt;  \\n&lt;b&gt;Date:&lt;/b&gt; Mon, 23 Jun 2025 17:56:53 +0000  \\n&lt;b&gt;Snippet:&lt;/b&gt; Hi Jane, I'm reaching out because we help companies like yours streamline operations. Last month, we helped Example Corp increase productivity by 25% while reducing costs...\\n\\n---\\n\\n&lt;b&gt;5. Subject:&lt;/b&gt; Re: [CompanyX/project-alpha] Fix/login issue (PR #41)  \\n&lt;b&gt;From:&lt;/b&gt; \\"system[bot]\\" &lt;a href=\\"<mailto:[email protected]>\\"&gt;[email protected]&lt;/a&gt;  \\n&lt;b&gt;To:&lt;/b&gt; \\"CompanyX/project-alpha\\" &lt;a href=\\"<mailto:[email protected]>\\"&gt;[email protected]&lt;/a&gt;  \\n&lt;b&gt;Date:&lt;/b&gt; Mon, 23 Jun 2025 10:53:11 -0700  \\n&lt;b&gt;Snippet:&lt;/b&gt; @system[bot] commented on this pull request. Issue: Authentication token validation needs improvement. The current implementation doesn't properly handle expired tokens...\\n\\n---\\n\\nWould you like to see the complete content of any specific email?",
  "exchange_id": "abc123def456ghi789jkl012mno345pqr"
}

Response Format