{
  "info": {
    "name": "ORYKSA API v1",
    "_postman_id": "0b5b1f0e-0f7c-4d7e-9d0a-0a7f0b0c0a01",
    "description": "ORYKSA API. Set the apiKey variable to your oryk_live_ key (Account > Developer). Docs: https://developer.oryksa.com",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{apiKey}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.oryksa.com"
    },
    {
      "key": "apiKey",
      "value": "oryk_live_..."
    },
    {
      "key": "clientToken",
      "value": "oryk_cs_..."
    }
  ],
  "item": [
    {
      "name": "Account",
      "item": [
        {
          "name": "API info",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1"
              ]
            },
            "description": "",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "Get account",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/account",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "account"
              ]
            },
            "description": "Plan, interaction usage, allowed domains and agent status."
          }
        },
        {
          "name": "Report conversion",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/conversions",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "conversions"
              ]
            },
            "description": "Tell ORYKSA that a conversation turned into a sale, lead, signup or booking. The owner is notified and it counts in the owner reports.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"kind\": \"sale\",\n  \"amount\": 129.9,\n  \"currency\": \"EUR\",\n  \"reference\": \"order-4812\",\n  \"conversation_id\": \"customer-4812\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        }
      ]
    },
    {
      "name": "Agent",
      "item": [
        {
          "name": "Update agent",
          "request": {
            "method": "PATCH",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/agent",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "agent"
              ]
            },
            "description": "Business details the AI agent uses to answer.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"business_name\": \"FitTrack\",\n  \"languages\": [\n    \"en\",\n    \"pt\"\n  ],\n  \"tone\": \"friendly\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "Update appearance",
          "request": {
            "method": "PATCH",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/agent/appearance",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "agent",
                "appearance"
              ]
            },
            "description": "Name, avatar and opening messages of the chat.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"greeting\": {\n    \"en\": \"Hi! How can I help?\"\n  }\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        }
      ]
    },
    {
      "name": "Knowledge",
      "item": [
        {
          "name": "Get knowledge",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/knowledge",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "knowledge"
              ]
            },
            "description": "What the agent knows (pages, FAQ items, services)."
          }
        },
        {
          "name": "Replace pages",
          "request": {
            "method": "PUT",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/knowledge/pages",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "knowledge",
                "pages"
              ]
            },
            "description": "Teach the agent your content. Replaces previous pages.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"pages\": [\n    {\n      \"url\": \"https://example.com/pricing\",\n      \"title\": \"Pricing\",\n      \"content\": \"Basic plan 9 EUR per month.\"\n    }\n  ]\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "Crawl website",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/knowledge/crawl",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "knowledge",
                "crawl"
              ]
            },
            "description": "Read a public website (up to 30 pages) and learn it.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"url\": \"https://example.com\",\n  \"max_pages\": 20\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "Add FAQ",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/knowledge/faq",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "knowledge",
                "faq"
              ]
            },
            "description": "Add or update question and answer pairs (max 100 per call).",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"items\": [\n    {\n      \"question\": \"Do you ship to Spain?\",\n      \"answer\": \"Yes, in 2 to 4 days.\"\n    }\n  ]\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        }
      ]
    },
    {
      "name": "Chat",
      "item": [
        {
          "name": "Send message",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/chat",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "chat"
              ]
            },
            "description": "Send a customer message and get the AI reply. Waits up to 40 s; returns 202 with status pending if the reply takes longer.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"message\": \"Do you open on Saturdays?\",\n  \"conversation_id\": \"user-42\",\n  \"customer_name\": \"Ana\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "List conversations",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/conversations",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "conversations"
              ],
              "query": [
                {
                  "key": "limit",
                  "value": "",
                  "disabled": true
                }
              ]
            },
            "description": ""
          }
        },
        {
          "name": "Get conversation",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/conversations/:conversation_id",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "conversations",
                ":conversation_id"
              ],
              "variable": [
                {
                  "key": "conversation_id",
                  "value": ""
                }
              ]
            },
            "description": ""
          }
        }
      ]
    },
    {
      "name": "Client sessions",
      "item": [
        {
          "name": "Create client session",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/sessions",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "sessions"
              ]
            },
            "description": "Server side only. Returns a short-lived oryk_cs_ token for ONE conversation, safe to give to an app.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"conversation_id\": \"user-42\",\n  \"customer_name\": \"Ana\",\n  \"ttl_minutes\": 60\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "Client send message",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/client/chat",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "client",
                "chat"
              ]
            },
            "description": "Called from the app with the client token. CORS enabled.",
            "auth": {
              "type": "bearer",
              "bearer": [
                {
                  "key": "token",
                  "value": "{{clientToken}}",
                  "type": "string"
                }
              ]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"message\": \"Hello\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "Client get messages",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/client/messages",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "client",
                "messages"
              ]
            },
            "description": "",
            "auth": {
              "type": "bearer",
              "bearer": [
                {
                  "key": "token",
                  "value": "{{clientToken}}",
                  "type": "string"
                }
              ]
            }
          }
        },
        {
          "name": "Client get agent",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/client/agent",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "client",
                "agent"
              ]
            },
            "description": "Name, avatar, greeting and suggestions for the chat UI.",
            "auth": {
              "type": "bearer",
              "bearer": [
                {
                  "key": "token",
                  "value": "{{clientToken}}",
                  "type": "string"
                }
              ]
            }
          }
        }
      ]
    },
    {
      "name": "Widget",
      "item": [
        {
          "name": "Get widget snippet",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/widget",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "widget"
              ],
              "query": [
                {
                  "key": "framework",
                  "value": "",
                  "disabled": true
                },
                {
                  "key": "lang",
                  "value": "",
                  "disabled": true
                },
                {
                  "key": "position",
                  "value": "",
                  "disabled": true
                }
              ]
            },
            "description": "Website chat code for your framework."
          }
        },
        {
          "name": "Set allowed domains",
          "request": {
            "method": "PUT",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/widget/domains",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "widget",
                "domains"
              ]
            },
            "description": "Restrict the website chat to these domains (empty list = any).",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"domains\": [\n    \"example.com\"\n  ]\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        }
      ]
    },
    {
      "name": "Webhooks",
      "item": [
        {
          "name": "List webhooks",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/webhooks",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "webhooks"
              ]
            },
            "description": ""
          }
        },
        {
          "name": "Create webhook",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/webhooks",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "webhooks"
              ]
            },
            "description": "The response includes the signing secret (shown once).",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"url\": \"https://example.com/oryksa/webhook\",\n  \"events\": [\n    \"message.replied\",\n    \"booking.created\"\n  ]\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "Delete webhook",
          "request": {
            "method": "DELETE",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/webhooks/:webhook_id",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "webhooks",
                ":webhook_id"
              ],
              "variable": [
                {
                  "key": "webhook_id",
                  "value": ""
                }
              ]
            },
            "description": ""
          }
        },
        {
          "name": "Test webhook",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/webhooks/:webhook_id/test",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "webhooks",
                ":webhook_id",
                "test"
              ],
              "variable": [
                {
                  "key": "webhook_id",
                  "value": ""
                }
              ]
            },
            "description": "Sends a signed webhook.test event."
          }
        }
      ]
    }
  ]
}