{
  "openapi": "3.0.4",
  "info": {
    "title": "Charla Public API",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://api.charla.com/v1"
    }
  ],
  "paths": {
    "/contacts": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "summary": "Retrieve all contacts using cursor-based pagination. \nThe results are sorted by contact last modification date in descending order, with a page size of 25 items.",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "description": "A pagination cursor returned by a previous request (Optional).  \nOmit this parameter to start from the beginning.  \nPass the value from the last item of a previous response to fetch the next page.",
            "schema": {
              "type": "integer",
              "format": "int64"
            },
            "example": 1757765348
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VisitorPublicApiResourcePublicApiPaging"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Contacts"
        ],
        "summary": "Save or update existing contact.",
        "requestBody": {
          "description": "The contact details object.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VisitorPublicApiResource"
              },
              "example": {"id":"58300e07-2cfa-4d6c-938c-b3a362edde05","name":"Adam","phone":"435-6356-45","email":"adam@charla.com","country_code":"en-US","location":"Miami, Florida","ip":"43.546.123.43","platform":"iPhone, iOS","browser_language":"en-US","custom_attributes":[{"value":"Charla","external_id":"company-43gt3"}]}
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/VisitorPublicApiResource"
              },
              "example": {"id":"58300e07-2cfa-4d6c-938c-b3a362edde05","name":"Adam","phone":"435-6356-45","email":"adam@charla.com","country_code":"en-US","location":"Miami, Florida","ip":"43.546.123.43","platform":"iPhone, iOS","browser_language":"en-US","custom_attributes":[{"value":"Charla","external_id":"company-43gt3"}]}
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/VisitorPublicApiResource"
              },
              "example": {"id":"58300e07-2cfa-4d6c-938c-b3a362edde05","name":"Adam","phone":"435-6356-45","email":"adam@charla.com","country_code":"en-US","location":"Miami, Florida","ip":"43.546.123.43","platform":"iPhone, iOS","browser_language":"en-US","custom_attributes":[{"value":"Charla","external_id":"company-43gt3"}]}
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VisitorPublicApiResource"
                },
                "example": {"id":"58300e07-2cfa-4d6c-938c-b3a362edde05","name":"Adam","phone":"435-6356-45","email":"adam@charla.com","country_code":"en-US","location":"Miami, Florida","ip":"43.546.123.43","platform":"iPhone, iOS","browser_language":"en-US","custom_attributes":[{"name":"Company","value":"Charla","external_id":"company-43gt3"}],"last_seen_at":"2026-10-20T01:11:02.6471712Z","last_message_at":"2026-10-20T01:11:02.6471713Z","created_at":"2026-10-20T01:11:02.6471714Z"}
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/contacts/{id}": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "summary": "Get Contact details by Id.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The Contat Id to retrieve.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "a9b259f5-3c3c-471e-86c7-3e69b3d83d25"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VisitorPublicApiResource"
                },
                "example": {"id":"58300e07-2cfa-4d6c-938c-b3a362edde05","name":"Adam","phone":"435-6356-45","email":"adam@charla.com","country_code":"en-US","location":"Miami, Florida","ip":"43.546.123.43","platform":"iPhone, iOS","browser_language":"en-US","custom_attributes":[{"name":"Company","value":"Charla","external_id":"company-43gt3"}],"last_seen_at":"2026-10-20T01:11:02.64815Z","last_message_at":"2026-10-20T01:11:02.6481501Z","created_at":"2026-10-20T01:11:02.6481501Z"}
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/conversations": {
      "get": {
        "tags": [
          "Conversations"
        ],
        "summary": "Retrieve all conversations per visitor using cursor-based pagination. \nThe results are sorted by the last message received per visitor in descending order, with a page size of 25 items.",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "description": "A pagination cursor returned by a previous request (Optional).  \nOmit this parameter to start from the beginning.  \nPass the value from the last item of a previous response to fetch the next page.",
            "schema": {
              "type": "integer",
              "format": "int64"
            },
            "example": 1757765348
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VisitorPublicApiResourcePublicApiPaging"
                }
              }
            }
          }
        }
      }
    },
    "/kb/articles/{id}": {
      "get": {
        "tags": [
          "Knowledge Base"
        ],
        "summary": "Get Article details by id.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The article Id to retrieve.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 43525
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KbArticlePublicApiResource"
                },
                "example": {"id":43525,"title":"How to use Charla API","slug":"how-to-use-charla-api","description":"A guide to using Charla.","article":"<p>Full article content here.</p>","categories":[{"id":1,"name":"General"}],"status":"Published","visibility":"Public","created_at":"2026-10-20T01:11:02.6502534Z","updated_at":"2026-10-20T01:11:02.6502535Z","trained_at":"2026-10-20T01:11:02.6502537Z"}
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/kb/articles": {
      "get": {
        "tags": [
          "Knowledge Base"
        ],
        "summary": "Retrieve all articles associated with a property using cursor-based pagination. \nThe results are sorted by creation date in descending order, with a page size of 25 items.",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "description": "An opaque pagination cursor (Optional).  \nOmit this parameter to start from the beginning.  \nPass the `next_cursor` value from the previous response to fetch the next page.",
            "schema": {
              "type": "string"
            },
            "example": "NjM4OTMzNjA5NDgxMjMwMDAwXzQzNTI1"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KbArticlePublicApiResourcePublicApiCursorPaging"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Knowledge Base"
        ],
        "summary": "Save or update existing articles. The article will be automatically used for chatbot training \nbased on the AI Chatbot settings and the types of articles configured for training.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KbArticlePublicApiResource"
              },
              "example": {"id":0,"title":"How to use Charla API","slug":"","description":"A guide to using Charla.","article":"<p>Full article content here.</p>","categories":[{"id":1}],"status":"Published","visibility":"Public"}
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/KbArticlePublicApiResource"
              },
              "example": {"id":0,"title":"How to use Charla API","slug":"","description":"A guide to using Charla.","article":"<p>Full article content here.</p>","categories":[{"id":1}],"status":"Published","visibility":"Public"}
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/KbArticlePublicApiResource"
              },
              "example": {"id":0,"title":"How to use Charla API","slug":"","description":"A guide to using Charla.","article":"<p>Full article content here.</p>","categories":[{"id":1}],"status":"Published","visibility":"Public"}
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KbArticlePublicApiResource"
                },
                "example": {"id":43525,"title":"How to use Charla API","slug":"how-to-use-charla-api","description":"A guide to using Charla.","article":"<p>Full article content here.</p>","categories":[{"id":1,"name":"General"}],"status":"Published","visibility":"Public","created_at":"2026-10-20T01:11:02.6527442Z","updated_at":"2026-10-20T01:11:02.6527444Z","trained_at":"2026-10-20T01:11:02.6527444Z"}
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/kb/article/{id}": {
      "delete": {
        "tags": [
          "Knowledge Base"
        ],
        "summary": "Delete an existing article by id.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Id of the article to be deleted.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/kb/categories": {
      "get": {
        "tags": [
          "Knowledge Base"
        ],
        "summary": "Get list of all categories.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/KbCategoryPublicApiResource"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "KbArticlePublicApiResource": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "slug": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "article": {
            "type": "string",
            "nullable": true
          },
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KbCategoryPublicApiResource"
            },
            "nullable": true
          },
          "status": {
            "type": "string",
            "description": "Status of the article, either Draft or Published",
            "nullable": true,
            "example": "Published"
          },
          "visibility": {
            "type": "string",
            "description": "Visibility of the article, either Private or Public",
            "nullable": true,
            "example": "Private"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "trained_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "KbArticlePublicApiResourcePublicApiCursorPaging": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KbArticlePublicApiResource"
            },
            "nullable": true
          },
          "paging": {
            "$ref": "#/components/schemas/PublicApiCursorPagingDetails"
          }
        },
        "additionalProperties": false
      },
      "KbCategoryPublicApiResource": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Category id, required when saving new articles.",
            "format": "int32",
            "example": 1
          },
          "name": {
            "type": "string",
            "description": "Name of the category",
            "nullable": true,
            "example": "Using Chatrla"
          },
          "parent": {
            "$ref": "#/components/schemas/KbCategoryPublicApiResource"
          }
        },
        "additionalProperties": false
      },
      "MessagePublicApiResource": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Visitor or Agent original message",
            "nullable": true,
            "example": "Hello there"
          },
          "message_translated": {
            "type": "string",
            "description": "Translated message if Live Translation was enabled",
            "nullable": true,
            "example": "Hola"
          },
          "from": {
            "type": "string",
            "description": "Either Visitor or Agent. Agent can be a live agent or a bot",
            "nullable": true,
            "example": "Visitor"
          },
          "is_private": {
            "type": "boolean",
            "description": "Whether the message was marked as private",
            "nullable": true,
            "example": false
          },
          "attachment": {
            "type": "string",
            "description": "Attachment Id if an attachment was attached to the message",
            "format": "uuid",
            "nullable": true
          },
          "article": {
            "type": "integer",
            "description": "Article Id if a knowledge base article was attached to the message",
            "format": "int32",
            "nullable": true,
            "example": 5
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "detail": {
            "type": "string",
            "nullable": true
          },
          "instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": { }
      },
      "PublicApiCursorPagingDetails": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of items without pagination.",
            "format": "int32",
            "nullable": true,
            "example": 25
          },
          "next_cursor": {
            "type": "string",
            "description": "An opaque pagination cursor to pass as `cursor` on the next request. Null when there is no next page.",
            "nullable": true,
            "example": "NjM4OTMzNjA5NDgxMjMwMDAwXzQzNTI1"
          },
          "has_next": {
            "type": "boolean",
            "description": "A boolean value indicating whether there is a next page.",
            "example": true
          }
        },
        "additionalProperties": false
      },
      "PublicApiPagingDetails": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of items without pagination.",
            "format": "int32",
            "nullable": true,
            "example": 25
          },
          "next_cursor": {
            "type": "integer",
            "description": "A pagination cursor you can use for subsequent requests.",
            "format": "int64",
            "nullable": true,
            "example": 1757765348
          },
          "has_next": {
            "type": "boolean",
            "description": "A boolean value indicating whether there is a next page.",
            "example": true
          }
        },
        "additionalProperties": false
      },
      "VisitorCustomAttributePublicApiResource": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Attribute Name",
            "nullable": true,
            "example": "Company"
          },
          "value": {
            "type": "string",
            "description": "Value of the custom attribute",
            "nullable": true,
            "example": "Charla"
          },
          "external_id": {
            "type": "string",
            "description": "External id of the custom attribute",
            "nullable": true,
            "example": "company-39415"
          }
        },
        "additionalProperties": false
      },
      "VisitorPublicApiResource": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique id of the contact",
            "format": "uuid",
            "nullable": true,
            "example": "a9b259f5-3c3c-471e-86c7-3e69b3d83d25"
          },
          "name": {
            "type": "string",
            "description": "Name of the visitor if available",
            "nullable": true,
            "example": "Adam"
          },
          "phone": {
            "type": "string",
            "description": "Phone of the visitor if available",
            "nullable": true,
            "example": "+201223461740"
          },
          "email": {
            "type": "string",
            "description": "Email of the visitor if available",
            "nullable": true,
            "example": "hello@site.com"
          },
          "country_code": {
            "type": "string",
            "description": "Country code in ISO 3166-1",
            "nullable": true,
            "example": "US"
          },
          "location": {
            "type": "string",
            "description": "Location per IP address",
            "nullable": true,
            "example": "Miami, Florida"
          },
          "ip": {
            "type": "string",
            "description": "IP address of the visitor",
            "nullable": true,
            "example": "82.48.123.43"
          },
          "platform": {
            "type": "string",
            "description": "Device used by the visitor",
            "nullable": true,
            "example": "iPhone, iOS"
          },
          "browser_language": {
            "type": "string",
            "description": "Browser language used by the visitor",
            "nullable": true,
            "example": "en-US"
          },
          "tags": {
            "type": "string",
            "description": "Tags to Attach to the visitor. Accepts one or multiple comma seperated tags. Note that the tag needs to be already added on the organization.",
            "nullable": true,
            "example": "lead, hot"
          },
          "custom_attributes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VisitorCustomAttributePublicApiResource"
            },
            "description": "Custom Attributes attached to the customer",
            "nullable": true
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MessagePublicApiResource"
            },
            "nullable": true
          },
          "last_seen_at": {
            "type": "string",
            "description": "Date where the visitor was last seen, either with or without an interaction",
            "format": "date-time",
            "nullable": true
          },
          "last_message_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "description": "Date where the visitor was initially created",
            "format": "date-time",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "VisitorPublicApiResourcePublicApiPaging": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VisitorPublicApiResource"
            },
            "nullable": true
          },
          "paging": {
            "$ref": "#/components/schemas/PublicApiPagingDetails"
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "description": "API Key needed to access the endpoints. Each property has its own API Key available under the Integration tab in the property settings. Example: <b>X-Api-Key: </b>adYD3v7xgCHX7izVzRfmK7RvIyNEq6obzBTInDRz6bNErI.",
        "name": "X-Api-Key",
        "in": "header"
      }
    }
  },
  "security": [
    {
      "ApiKey": [ ]
    }
  ]
}