> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Create a custom instruction POST https://example.ada.support/api/v2/custom-instructions/ Content-Type: application/json Create a new custom instruction for the AI Agent. New instructions default to inactive (`enabled: false`); enable one by setting `enabled: true` on create or via a later update. Reference: https://docs.ada.cx/reference/custom-instructions/create-custom-instruction ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects a CustomInstructionCreate. - `title` (string, required) — Display name for the custom instruction (unique per Agent) - `text` (string, required) — The instruction content — the rule the Agent should follow - `enabled` (boolean, optional, default: false) — Whether the instruction is enabled. False means inactive. - `notes` (string, optional) — Internal notes about this instruction (not shown to the Agent) - `availability_rules` (string, optional, nullable) — Optional availability rule as a rule-expression string with `v("")` lookups. Omit or send `null` for no rule. A rule that references an unknown variable, or that is malformed or uses an unsupported operator, is rejected with 400. ## Response ### 201 Created - `id` (string, required) — The unique identifier for the custom instruction - `title` (string, required) — Display name for the custom instruction (unique per Agent) - `text` (string, required) — The instruction content — the rule the Agent should follow - `enabled` (boolean, required, default: false) — Whether the instruction is enabled. False means inactive. - `notes` (string, optional, nullable) — Internal notes about this instruction (not shown to the Agent) - `availability_rules` (string, optional, nullable) — Availability rule gating which end users this instruction applies to, as a rule-expression string with `v("")` variable lookups. `null` when no rule is set. ## Errors ### 400 Bad Request Error Bad Request - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 401 Unauthorized Error Unauthorized - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 409 Conflict Error Conflict — the title is already used by another custom instruction, or enabling would exceed the AI Agent's enabled-instruction limit - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 429 Too Many Requests Error Too Many Requests - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 500 Internal Server Error Internal Server Error - `errors` (list of ErrorsErrorsItems, required) — A list of errors ## Types ### ErrorsErrorsItems - `type` (string, required) — The error type - `message` (string, required) — The error message - `details` (string, optional, nullable) — Extra information about the error ## Examples **Request** ```json { "title": "Refund policy", "text": "Always confirm the order number before issuing a refund.", "enabled": false, "notes": "Reviewed by the CX team." } ``` **Response** ```json { "id": "65a17e3f43bec88e2792d0eb", "title": "Refund policy", "text": "Always confirm the order number before issuing a refund.", "enabled": true, "notes": "Reviewed by the CX team." } ``` **SDK Code** ```python import requests url = "https://example.ada.support/api/v2/custom-instructions/" payload = { "title": "Refund policy", "text": "Always confirm the order number before issuing a refund.", "enabled": False, "notes": "Reviewed by the CX team." } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://example.ada.support/api/v2/custom-instructions/'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"title":"Refund policy","text":"Always confirm the order number before issuing a refund.","enabled":false,"notes":"Reviewed by the CX team."}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://example.ada.support/api/v2/custom-instructions/" payload := strings.NewReader("{\n \"title\": \"Refund policy\",\n \"text\": \"Always confirm the order number before issuing a refund.\",\n \"enabled\": false,\n \"notes\": \"Reviewed by the CX team.\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://example.ada.support/api/v2/custom-instructions/") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"title\": \"Refund policy\",\n \"text\": \"Always confirm the order number before issuing a refund.\",\n \"enabled\": false,\n \"notes\": \"Reviewed by the CX team.\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://example.ada.support/api/v2/custom-instructions/") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"title\": \"Refund policy\",\n \"text\": \"Always confirm the order number before issuing a refund.\",\n \"enabled\": false,\n \"notes\": \"Reviewed by the CX team.\"\n}") .asString(); ``` ```php request('POST', 'https://example.ada.support/api/v2/custom-instructions/', [ 'body' => '{ "title": "Refund policy", "text": "Always confirm the order number before issuing a refund.", "enabled": false, "notes": "Reviewed by the CX team." }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://example.ada.support/api/v2/custom-instructions/"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"title\": \"Refund policy\",\n \"text\": \"Always confirm the order number before issuing a refund.\",\n \"enabled\": false,\n \"notes\": \"Reviewed by the CX team.\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "title": "Refund policy", "text": "Always confirm the order number before issuing a refund.", "enabled": false, "notes": "Reviewed by the CX team." ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://example.ada.support/api/v2/custom-instructions/")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```