Ask PCIFIC

Give customers AI answers with checked sources and optional word-for-word quotes.

Your server sends a customer's question. Ask PCIFIC reads your documents and returns a short answer with sources and optional quotes. You build the question box. Citations always point to a real source Ask has read, and quotes are checked word for word. Ask is instructed to stay within its sources, but a sentence can occasionally add general advice that is not in them.

Ask PCIFIC supports English only; other languages are not supported yet.

What an answer means

  • answered: the AI wrote an answer. It is instructed to use your live documents, the item you sent and, only if you allow it, web sources. sources identifies the real sources it read, without guaranteeing support for every sentence. Neutral explanations of general terms may use general knowledge without a source; they do not establish facts about this listing.
  • Quote blocks are optional by default. Send quotes: true to request one whenever a document supports the answer. If the AI omits a valid quote, PCIFIC includes the first paragraph of a cited section. quoteAvailable is true when the answer includes a verified quote, otherwise false. No internal quote message is added to the buyer answer. A quote is the document's own words. Before it is sent, PCIFIC checks the words are really in that section of that document. A quote that does not match is removed, and so is any source tag that points at something the AI was not shown.
  • The sentences around a quote are the AI's own wording. It can still misread a policy, so show the sources beside the answer, and do not treat an answer as legal or financial advice.
  • An answer is only as complete and as current as your documents. A version waiting for approval does not answer yet.
  • not_covered: nothing you wrote covered the question. The answer is your fallback message (the standard one until you set your own), supportLink is filled in, and the question goes on your unanswered list so you know what to write next.
  • Show aiNotice beside every answer, so people know an AI wrote it. You set the notice in your shop settings.

How you can use it

Real questions Ask PCIFIC answers
Who asksExample questionsDocuments to addItem to send
A buyer on a shop listingCan I return this if I change my mind? When will it arrive?Returns policy, delivery policy, buyer protection pageThe listing: its id, title and details such as condition
An insurance customerDoes my cover include water damage? How do I make a claim?Policy wording (PDF or Word), claims guideThe cover being looked at, for example type policy and a title such as Home contents, Standard
A guest on a rental pageIs there a deposit? Can I cancel for free?House rules, cancellation policyThe property or booking with its details
A visitor on a support or help pageHow do I reset my password?Your help pages, each added as a web address so they are checked dailyNothing
A business customerWhat warranty comes with this part? Is there a minimum order?Trade terms, delivery terms, warranty termsThe product, found by its id from your own system (item lookup)

The same tool works for every row: the documents and the item change, nothing else does. An item can be anything a customer is looking at: a listing, a product, a policy, a property or a booking.

Before you start

  • An API key (a secret password your server sends with each request). A test key needs the ask-pcific permission to ask, the documents permission to add documents, and the settings permission to change settings or item lookup. Live keys, test keys and permissions are on the API keys and permissions page.
  • At least one live document. Without one, a question is refused with ASK_NO_DOCUMENTS.
  • Ask PCIFIC switched on. It is on by default (enabled in the settings).
  • A name for your business in the shared shop settings. The AI answers on behalf of that name. Shop configuration also holds the aiNotice you show beside each answer.
  • A server of your own that calls PCIFIC. Never put the key in a web page or an app, where anyone could copy it, and never call Ask PCIFIC from the customer's browser.

How it works

From your documents to a quoted answer
  1. You add documentsPaste text, upload a file (PDF, Word, web page, Markdown or text) or give a public https web page. Use the dashboard Documents page or POST /api/v1/documents.
  2. PCIFIC turns each one into sectionsIt becomes Markdown (plain text that keeps its headings), then splits at each heading into numbered sections. No AI is used here, so nothing can be made up.
  3. A version goes live, or waitsEvery change is a new version. With reviewMode automatic it answers at once. With approve_first it waits until an owner or admin approves it on the dashboard.
  4. Your server sends a questionPOST /api/v1/ask-pcific with the question and, if you have one, the item the customer is looking at.
  5. The AI opens what it needsIt picks documents by title and headings and reads them, may look up another item, and may search the web (up to 2 searches). It has 30 seconds and up to 4 rounds of tool use.
  6. You get the answer and its sourcesParagraphs with source references, checked quotes and page links. If nothing covers the question you get status not_covered and your fallback message.

Answer and block text contain no citation tags. Each text block has a separate sources list naming the document section, listing or web page it used. Source number starts at 1 for each answer; show that number beside the relevant block. Quote blocks refer to sourceNumber. Internal tag, documentId and itemId are for your server, not buyer-facing labels. The AI is instructed to put your shop documents before seller wording on policy questions and to use supplied sources for facts about the listing, seller, deal and shop. Ask can still explain general concepts neutrally; judgments about a particular seller or deal need to be stated in a document or the listing.

What the AI can use

  • Your live documents. It sees a list of their titles and main headings, chooses the ones that fit the question, and opens them in full.
  • The item you sent, or one looked up from your own system by its id. Item text is treated as information only: if a seller writes "ignore your instructions" in a listing, the AI does not follow it.
  • Web search, only if webSearch is on (it is by default). It is for general facts such as a product's specifications, and the AI is told never to use it for your own policies. One search reads the top 3 pages, and an answer can search at most 2 times.
  • Your tone notes, or the shared voice from your shop settings if you set none, as style only. They cannot change what the AI is allowed to say.

Quickstart

These steps use a test key in $PCIFIC_TEST_KEY with the documents, ask-pcific and settings permissions. The ids and times in the answers are examples, yours will differ. These example answers show successful source use; other answers can occasionally include general advice absent from their sources.

Document uploads share a bounded allowance across the API and dashboard: eight uploads and 64 MiB of reserved input per server, with two uploads and 22 MiB per business across all shops and keys. Web-address downloads and refreshes share this allowance; busy background refreshes stay due for the next run. PCIFIC reserves Content-Length before reading; a missing length reserves the full 10 MiB plus 64 KiB request allowance, and real streamed bytes are checked. PDF conversion waits at most two seconds for a reader. A 429 DOCUMENT_UPLOAD_LIMIT means your business is at its share; 503 DOCUMENT_UPLOAD_BUSY means server capacity is full or the PDF wait ended. Both include Retry-After: 20. Try the upload again after 20 seconds. A 408 DOCUMENT_UPLOAD_TIMEOUT means the body did not finish arriving within 20 seconds: check your connection and retry, or split a large file. These limits also cover Word, HTML, Markdown and text files, JSON documents and replacements.

Step 1: add a document

Headings written as # Heading become sections. The answer is 201 (created) and the document is live straight away, because reviewMode is automatic by default.

Add a returns policy
curl -X POST https://business.pcific.ai/api/v1/documents \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Returns policy","text":"# Who can return\nYou can return any item within 30 days of delivery.\n\n# Refunds\nRefunds go back to your original payment method within 5 working days of us getting the item."}'
Response, 201
{
  "id": "9c1f5b0e-3d6a-4a52-8f55-2b7d1c0a4e11",
  "title": "Returns policy",
  "source": "text",
  "url": null,
  "fileName": null,
  "status": "live",
  "published": true,
  "liveVersion": {
    "id": "e07a4c19-6b2d-4f38-a1c5-83d9b0f2c764",
    "createdAt": "2026-10-19T09:00:00.512Z",
    "characters": 173,
    "approvedAt": "2026-10-19T09:00:00.512Z",
    "approvedBy": null
  },
  "waitingVersion": null,
  "lastCheck": null,
  "lastChangedAt": null,
  "createdAt": "2026-10-19T09:00:00.512Z",
  "updatedAt": "2026-10-19T09:00:00.512Z",
  "warnings": []
}

You can instead give a web address, which PCIFIC copies now and checks daily, or upload a file. See Documents below. A document added from a web address also lets answers show a page link to it.

Step 2: ask a question

Ask PCIFIC
curl -X POST https://business.pcific.ai/api/v1/ask-pcific \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Can I return this coat if I change my mind?","quotes":true,"item":{"type":"listing","title":"Wool coat, navy, size M","details":{"condition":"Used, good","status":"Available"}}}'
Response, 200
{
  "conversationId": "4b0c2d7e-5a3f-4c1e-9b7a-2e8d6f1a0c35",
  "status": "answered",
  "answer": "Yes. You can return it within 30 days of delivery.\n\n\"You can return any item within 30 days of delivery.\"",
  "blocks": [
    {
      "type": "text",
      "text": "Yes. You can return it within 30 days of delivery.",
      "sources": [
        {
          "number": 1,
          "tag": "d1.1",
          "type": "document",
          "documentId": "9c1f5b0e-3d6a-4a52-8f55-2b7d1c0a4e11",
          "document": "Returns policy",
          "section": 1,
          "heading": "Who can return"
        }
      ]
    },
    {
      "type": "quote",
      "text": "You can return any item within 30 days of delivery.",
      "sourceNumber": 1,
      "documentId": "9c1f5b0e-3d6a-4a52-8f55-2b7d1c0a4e11",
      "document": "Returns policy",
      "section": 1,
      "heading": "Who can return"
    }
  ],
  "sources": [
    {
      "number": 1,
      "tag": "d1.1",
      "type": "document",
      "documentId": "9c1f5b0e-3d6a-4a52-8f55-2b7d1c0a4e11",
      "document": "Returns policy",
      "section": 1,
      "heading": "Who can return"
    }
  ],
  "quoteAvailable": true,
  "supportLink": null,
  "aiNotice": "Generated with our company AI. Please verify the information before relying on it.",
  "release": "2.0.0",
  "warnings": []
}

Show the blocks in order: a text block as a paragraph, a quote block as a quote with its document and section, and a page block as a card or button that opens the link. Keep conversationId to carry on the chat.

Step 3: carry on the chat

Send the conversationId from the last answer with the customer's next question. The AI then sees the last 8 turns of the chat. Leave it out to start a new chat.

A follow-up question
curl -X POST https://business.pcific.ai/api/v1/ask-pcific \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"How long do refunds take?","conversationId":"4b0c2d7e-5a3f-4c1e-9b7a-2e8d6f1a0c35"}'

Step 4: when nothing covers the question

A question the documents do not answer
curl -X POST https://business.pcific.ai/api/v1/ask-pcific \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Do you ship to Norway?"}'
Response, 200
{
  "conversationId": "4b0c2d7e-5a3f-4c1e-9b7a-2e8d6f1a0c35",
  "status": "not_covered",
  "answer": "I couldn't find the answer to that in our information. Please contact our support team.",
  "blocks": [
    {
      "type": "text",
      "text": "I couldn't find the answer to that in our information. Please contact our support team.",
      "sources": []
    }
  ],
  "sources": [],
  "quoteAvailable": false,
  "supportLink": "https://example.com/help",
  "aiNotice": "Generated with our company AI. Please verify the information before relying on it.",
  "release": "2.0.0",
  "warnings": []
}

Show the fallback message and offer supportLink. This is not an error: the status is 200. supportLink is null on an answered answer, and it is the support link you set in the settings.

Step 5: read the questions nothing covered

Unanswered questions
curl -X GET https://business.pcific.ai/api/v1/ask-pcific/unanswered?limit=20 \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY"
Response, 200
{
  "questions": [
    {
      "question": "Do you ship to Norway?",
      "reason": "No document says which countries we deliver to",
      "askedAt": "2026-10-19T09:14:03.221Z"
    }
  ]
}

Newest first. Add a document that covers each one and the next customer gets an answer. An unanswered question is kept for 30 days, and not at all while Ask PCIFIC is on the True ZDR privacy tier (see Monitoring and privacy).

Streaming the answer

Showing the answer as it is written
  1. Send the same request with Accept: text/event-streamSSE (server-sent events) is a way for a server to send a reply in pieces over one connection.
  2. PCIFIC checks the requestA wrong key, a bad body or a switched off tool is refused right away as a normal JSON error with an HTTP status. Nothing streams.
  3. Each finished paragraph is checked and sentRender each text event immediately as a paragraph with its numbered sources. Render quote events with sourceNumber and page events as links in their arrival order. Text and quotes are checked before release and never withdrawn. Blocks arrive paragraph by paragraph, never token by token. Tools and the AI provider can delay the first paragraph.
  4. A done event ends the answerThe final paragraph is sent when the AI finishes, then done carries the same fields as the JSON answer, except blocks (you already have them). Keep conversationId and the final answer; do not append the answer again after rendering the blocks.
  5. Or an error event ends itIf something fails after the stream started, the last event is error. Pass the events on to the browser through your own server, so the key stays on it.
Stream an answer
curl -N -X POST https://business.pcific.ai/api/v1/ask-pcific \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"question":"Can I return this coat if I change my mind?","quotes":true,"item":{"type":"listing","title":"Wool coat, navy, size M","details":{"condition":"Used, good","status":"Available"}}}'
The events
event: text
data: {"type":"text","text":"Yes. You can return it within 30 days of delivery.","sources":[{"number":1,"tag":"d1.1","type":"document","documentId":"9c1f5b0e-3d6a-4a52-8f55-2b7d1c0a4e11","document":"Returns policy","section":1,"heading":"Who can return"}]}

event: quote
data: {"type":"quote","text":"You can return any item within 30 days of delivery.","sourceNumber":1,"documentId":"9c1f5b0e-3d6a-4a52-8f55-2b7d1c0a4e11","document":"Returns policy","section":1,"heading":"Who can return"}

event: done
data: {"conversationId":"4b0c2d7e-5a3f-4c1e-9b7a-2e8d6f1a0c35","status":"answered","answer":"Yes. You can return it within 30 days of delivery.\n\n\"You can return any item within 30 days of delivery.\"","sources":[{"number":1,"tag":"d1.1","type":"document","documentId":"9c1f5b0e-3d6a-4a52-8f55-2b7d1c0a4e11","document":"Returns policy","section":1,"heading":"Who can return"}],"quoteAvailable":true,"supportLink":null,"aiNotice":"Generated with our company AI. Please verify the information before relying on it.","release":"2.0.0","warnings":[]}
Stream events
EventWhat it carries
textA paragraph of the answer, with its sources. The same object as a text block.
quoteA document's exact words with the document, section and heading they come from.
pageA document's title and link, to show as a card or button.
doneThe finished answer: conversationId, status, answer, sources, supportLink, aiNotice, release and warnings.
error{error, code, tryThis}: the same three parts as any error. It always ends the stream.
a comment lineA line starting with a colon arrives every 15 seconds while the AI works, to keep the connection open. Ignore it.

Request fields

POST /api/v1/ask-pcific takes JSON, at most 16 KB. A field it does not know is ignored and named in warnings, so a typo shows up there rather than failing the question.

Request body
FieldTypeRequiredWhat it is
questionstringYesThe customer's question, 1 to 1,500 characters. Ask PCIFIC supports English only; other languages are not supported yet.
quotesbooleanNoOptional, false by default. Request at least one verified document quote when a document supports the answer. If the AI omits it, PCIFIC uses the first paragraph of a cited section. quoteAvailable tells you whether the answer includes a verified quote; no internal message is added to the buyer answer. Without true, quote blocks are optional.
modelTierstringNostandard (the default) or ultra-fast. Ultra Fast answers in about half a second instead of several, and a live use spends more credits: the Credits page in your dashboard shows how many. A use is charged as Ultra Fast only when Ultra Fast answered the whole request; otherwise Standard answers and it is charged as Standard. A business on its own AI key is answered by its own model. null is the same as leaving it out.
conversationIdstringNoLeave it out, or send null, to start a new chat. Send the one from the last answer to carry on, so the AI sees the last 8 turns.
buyerobjectNoThe asking buyer, supplied by your shop server. Only accountId is accepted inside buyer; unknown keys return ASK_ACCOUNT_ID_INVALID, naming the key and what to send instead. null is the same as leaving it out.
buyer.accountIdstringNoOpaque account id, never a name or username. 1 to 128 ASCII letters, digits, dots, colons, underscores or hyphens. Compared only in the backend, never sent to the AI. Sent to item lookup as the buyerAccountId query parameter, including get_item. null is the same as leaving it out.
itemobjectNoThe item the customer is looking at: a listing, product, policy, property or booking. Only item.id is needed when item lookup is set up. null is the same as leaving it out.
item.idstring | integerNoYour own id for the item, text or a whole number, 1 to 128 characters, for example "coat-8841" or 8841. Requires listing lookup; otherwise the request is refused with ASK_ITEM_LOOKUP_NOT_CONFIGURED before AI work. A number is read as its digits. With lookup set up, PCIFIC looks the item up by this id and ignores every other item field. null is the same as leaving it out.
item.typestringNoAny word for what it is, such as listing or booking. Up to 40 characters. null leaves it out.
item.titlestringNoUp to 300 characters. null leaves it out.
item.urlstringNoUp to 2,000 characters. The AI sees it. PCIFIC never opens it. null leaves it out.
item.reservedForAccountIdstringNoOpaque account id of the buyer holding the reservation, never a name or username. Same 1 to 128 character rules as buyer.accountId. Matching ids mean reserved for you; different ids mean unavailable, reserved by another buyer. An explicit null reservedForAccountId means not reserved. Otherwise, if either id is missing, ownership cannot be confirmed. Only the comparison result reaches the AI; neither id is returned. With neither id establishing a reservation, an explicit Available or Not reserved status means not reserved.
item.priceobjectNoOptional price, using the shared Orbit and Safeguard money format. For example {amount: 9575, currency: GBP} means £95.75 GBP. With lookup, return price at the top level of the lookup JSON. Only objects with exactly amount and currency use this contract; other shapes, including legacy {value, currency} objects, stay ordinary listing details.
item.price.amountintegerYesNonnegative whole number in the currency's smallest unit, such as pence or cents. Never a decimal or text. Yen has no smaller unit.
item.price.currencystringYesThree letter currency code in capitals, for example GBP, USD or JPY. Ask displays the amount with that currency and never converts it.
item.detailsobjectNoListing facts a customer might ask about, as names and values. Include item.details.status as text stating current availability. Reservation ownership comes only from comparing buyer.accountId with item.reservedForAccountId, never from seller wording. With item lookup, return status, reservedForAccountId and price at the top level of the lookup JSON. Seller wording cannot override your shop policy documents. Up to 60 entries. Each value is plain: text up to 2,000 characters, a number, true, false or null. The names are your own and are passed on exactly as sent. null for the whole object is the same as leaving it out.
item.details.{name}string | number | booleanNoOne listing fact under your own name for it, such as condition or status. Text up to 2,000 characters, a number, true, false or null.

Send item.details.status with the current availability. Send buyer.accountId for the asking buyer and item.reservedForAccountId for the reservation holder, as opaque account ids, never names or usernames. The backend compares them and only sends the result to the AI: matching ids mean reserved for you; different ids mean unavailable, reserved by another buyer; an explicit null reservedForAccountId means not reserved; otherwise either id missing means ownership cannot be confirmed. An explicit Available or Not reserved status with no reservation holder means not reserved. Neither id reaches the AI. With item lookup, Ask sends buyer.accountId as the buyerAccountId query parameter, including get_item; return status, reservedForAccountId and price at the top level of the lookup JSON. Only price objects with exactly amount and currency use the structured contract. Other shapes, including legacy {value, currency} objects, stay ordinary listing details. If a lookup field is invalid, correct the named field in your configured lookup response and test it again. Never infer reservation ownership from seller wording. Optional item.price uses {amount: 9575, currency: GBP} for £95.75 GBP, the same money format as Orbit and Safeguard. Use a nonnegative whole number in the smallest unit, such as 4500 pence for £45, and a three letter currency code in capitals. Decimal points, exponents and text amounts are refused with 400 ASK_PRICE_INVALID. If you have set up item lookup and send item.id, PCIFIC looks the item up itself and ignores every other item field you sent, so a customer cannot change a price. A warning says so. If you send item.id without item lookup, the request is refused with 400 ASK_ITEM_LOOKUP_NOT_CONFIGURED before AI work. Set up item lookup, or leave item.id out and send the listing details instead.

Response fields

Response body
FieldTypeRequiredWhat it is
conversationIdstringYesThe chat. Send it with the customer's next question. null when you have switched chats off.
statusstringYesanswered, or not_covered when nothing you wrote covered the question.
answerstringYesThe whole answer as plain text, without citation tags. It can occasionally add general advice absent from its sources. Quotes are in quote marks and pages are written "title: link".
blocksobject[]YesThe answer in reading order. Only in the JSON answer, not in a stream. Each has a type: text (a paragraph with its sources), quote (the document's exact words with their document and section) or page (a document's title and link).
sourcesobject[]YesEvery cited source across all blocks, each once. number starts at 1 for each answer; display it beside the relevant block. type is document, item or web. Internal tag, documentId and itemId remain available for your server; use number as the buyer-facing label. Citations identify real sources the AI read, without checking support for each sentence. Text blocks have their own sources; quote blocks use sourceNumber.
quoteAvailablebooleanYesWhether this answer includes a verified document quote. False adds no message to the buyer answer.
supportLinkstringYesYour support link, only when status is not_covered. Otherwise null.
aiNoticestringYesThe notice to show beside the answer, from your shop settings. null when you chose none.
modelTierobjectYesWhich tier answered: {requested, handledBy, message}.
modelTier.requestedstringYesstandard or ultra-fast, as the request asked.
modelTier.handledBystringYesThe tier that answered the whole request: standard, ultra-fast, or byo when your own AI key answered. A use is charged as Ultra Fast only when this is ultra-fast.
modelTier.messagestringYesWhy handledBy differs from requested, else null.
releasestringYesThe Ask PCIFIC release that answered. Always "2.0.0" today.
warningsstring[]YesFields you sent that PCIFIC ignored, and why.
The three kinds of block
typeWhat it isFields
textA paragraph with tag-free text and a separate list of numbered sources.type, text, sources
quoteThe document's exact words. Spacing, curly quotes, dashes and bold or italic marks do not count as differences, and "..." in a quote may skip text.type, text, sourceNumber, documentId, document, section, heading
pageA document's title and link, to show as a card or button. Only documents added from a web address have a page.type, documentId, title, url
The three kinds of source
typeWhat it isFields
documentA part of one of your documents. section and heading are left out when the tag names the whole document, like [d1].number, tag, type, documentId, document, section, heading
itemThe item the customer is looking at (tag item), or another item the AI looked up (tag i1, i2...).number, tag, type, itemId
webA web page the search found (tag w1, w2...). Only when web search is on.number, tag, type, title, url

Chats

  • Every answer is saved to a chat and returns its conversationId. Send it with the next question and the AI sees the last 8 turns.
  • A chat is deleted 30 days after its last question.
  • One chat can ask at most 20 questions a minute. A person cannot type that fast, so more means a bot or your code sending a question again and again. The next one gets ASK_CHAT_TOO_FAST until the minute has passed. Other chats are not affected.
  • To keep no chats, set keepChats to false. Each question is then answered on its own, conversationId comes back null, and sending one is refused with ASK_CHATS_OFF.

Documents

Add the documents you want Ask PCIFIC to use. An owner or admin can manage them on the dashboard Documents page, or your own system can do it over the API with a key that has the documents permission.

Three ways to add a document
WayWhat you send
Paste textPOST /api/v1/documents as JSON {"title": "Returns policy", "text": "..."}. The title is required.
Give a web addressJSON {"url": "https://example.com/returns"}. The title is optional and defaults to the page's own title. PCIFIC copies it now and checks it daily.
Upload a filemultipart/form-data with the file in a part named file, and optionally a title. A PDF, Word (.docx), web page (.html), Markdown (.md) or text (.txt) file, up to 10 MB. The title defaults to the file name.
Add a web page checked daily
curl -X POST https://business.pcific.ai/api/v1/documents \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/returns"}'
Upload a file
curl -X POST https://business.pcific.ai/api/v1/documents \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -F file=@warranty.docx \
  -F title="Warranty"

What happens to a document

  • A web page loses its menus, headers, footers, scripts, forms and buttons, so a cookie banner never becomes the document. A page with no readable text after conversion is refused.
  • A Word file keeps its Title and Heading 1 to 6 styles as headings, and list paragraphs become bullets. A Word file's text may unpack to 20 MB at most.
  • A PDF becomes plain text and has no real headings, so it is one section unless it is long. A scanned PDF is a picture of text, so it comes out empty and is refused with DOCUMENT_EMPTY: paste its text instead. A PDF that takes too long to read (20 seconds) or too much memory is refused with DOCUMENT_UNREADABLE.
  • Text, Markdown and web page files must be UTF-8 (the usual way of saving text). Anything else is refused with DOCUMENT_UNREADABLE.
  • Documents are your business's own content, so short text such as "Free delivery." is accepted. Empty documents are refused with DOCUMENT_EMPTY, and binary or damaged text is refused with DOCUMENT_UNREADABLE. A web page file with no HTML tags is refused with DOCUMENT_NOT_HTML: upload the real page, or save the text as .txt. A web page with no readable text after conversion is refused with DOCUMENT_EMPTY.
  • Text before the first heading becomes its own section, headed with the document's title. A section longer than 6,000 characters is split again at paragraph breaks into parts that share its heading.
  • A web address must be https, have no user name or password in it, and reach a public server (not a private or local one). The check is repeated on each redirect, with at most 5 redirects.
A document, as every documents address shows it
FieldTypeRequiredWhat it is
idstringYesThe document.
titlestringYesIts title.
tagsstring[]YesOptional document labels, returned as [] when none are set. Up to 5 different lowercase words, each 1 to 24 letters (a to z).
sourcestringYesHow it was added: text, file or url.
urlstringYesThe web page, for a url document.
fileNamestringYesThe cleaned uploaded name, for a file document. Folders, control characters and .. are removed. If nothing remains, PCIFIC uses a document name based on the Content-Type.
statusstringYeslive (it is answering), waiting (only a version waiting for approval, so it does not answer yet), not_live (its only version was rejected), or unpublished (kept but not used for answers).
publishedbooleanYesfalse keeps the document and versions but stops Ask PCIFIC using it.
liveVersionobjectYes{id, createdAt, characters, approvedAt, approvedBy} of the approved version, or null. approvedAt is UTC ending in Z. approvedBy is {name, role}, or null for an automatic approval.
waitingVersionobjectYesThe same for a version waiting for an owner or admin to approve it, or null.
lastCheckobjectYesWeb page documents only, otherwise null: {at, ok, error, tryThis}. ok is false when the last read failed, and the last good version keeps answering.
lastChangedAtstringYesWebsite documents only, otherwise null. UTC time when changed text was last saved, including an update waiting for approval. Unchanged checks leave it alone.
createdAtstringYesWhen it was added.
updatedAtstringYesWhen it last changed.
liveVersion.idstringYesThe version.
liveVersion.createdAtstringYesWhen it was made.
liveVersion.charactersintegerYesIts length once converted to text.
liveVersion.approvedAtstringYesWhen it was approved, in UTC ending in Z. Always null for a waiting version.
liveVersion.approvedByobjectYesWho approved it, or null for an automatic approval. Always null for a waiting version.
liveVersion.approvedBy.namestringYesThe name of the person who approved it, or Former member when they have left the business.
liveVersion.approvedBy.rolestringYesTheir role when they approved it, such as owner or admin. null when it was not recorded.
waitingVersion.idstringYesThe version.
waitingVersion.createdAtstringYesWhen it was made.
waitingVersion.charactersintegerYesIts length once converted to text.
waitingVersion.approvedAtstringYesWhen it was approved, in UTC ending in Z. Always null for a waiting version.
waitingVersion.approvedByobjectYesWho approved it, or null for an automatic approval. Always null for a waiting version.
waitingVersion.approvedBy.namestringYesThe name of the person who approved it, or Former member when they have left the business.
waitingVersion.approvedBy.rolestringYesTheir role when they approved it, such as owner or admin. null when it was not recorded.
lastCheck.atstringYesWhen PCIFIC last read the page, in UTC.
lastCheck.okbooleanYesfalse when the last read failed. The last good version keeps answering.
lastCheck.errorstringYesWhy the last read failed, or null when it worked.
lastCheck.tryThisstringYesWhat to try next when the last read failed, or null when it worked.

Changes, versions and approval

How a change reaches your customers
  1. Something changesYou send new text or a file to PUT /api/v1/documents/{id}/content, a web page document is re-read and its page changed, or an owner or admin replaces it on the dashboard.
  2. PCIFIC makes a new versionSending exactly the same content again makes nothing new (the answer says changed: false), so your system can push on every deploy.
  3. It goes live, or waitsWith reviewMode automatic the new version answers from the next question. With approve_first it waits, and the live version keeps answering meanwhile.
  4. A person decides on the dashboardAn owner or admin opens the Documents page, compares the waiting version with the live one, and chooses Approve or Reject.
  5. Approved versions answerThe approved version goes live and the old one becomes replaced. A rejected version is discarded. A brand new document in this mode answers nothing until its first version is approved.

No API key, test or live, can approve or reject a waiting version. The key sits on your servers, and a leaked one must not be able to put new policy wording in front of customers. POST /api/v1/documents/{id}/versions/{versionId} is for the dashboard only, and an API key that calls it gets 403 DOCUMENT_DECISION_NEEDS_DASHBOARD. Use GET on a document to see its waiting version, and tell an owner or admin to decide.

  • A document's status is live (it answers), waiting (only a version waiting for approval, so it answers nothing yet), not_live (its only version was rejected), or unpublished (kept but not used for answers). A version's status is live, waiting, rejected or replaced.
  • The live version, a waiting version and the newest 5 versions in all are kept. Older ones are removed.
  • Only an owner or admin can change reviewMode on the dashboard Documents page. API keys receive 403 REVIEW_MODE_NEEDS_DASHBOARD when they send this setting.
  • Remove on the dashboard stops answers from using the document immediately. Its notice offers Undo for 10 seconds, restoring the same document, tags, versions, approval history and publication state. After 10 seconds removal is final, even if you leave the page. Only owners and admins of your business can undo. Deleting with an API key is permanent immediately and has no Undo.

Text sent as JSON and uploaded UTF-8 text or Markdown is stored exactly as given, including spaces and trailing newlines. Download a version with GET /api/v1/documents/{id}/versions/{versionId} and read markdown to get that same text. Other file formats are converted to Markdown.

Uploaded file names are cleaned before they are stored or returned: folder names, control characters and .. are removed. If nothing remains, PCIFIC uses a document name based on the file's Content-Type.

Document tags and filters

Use optional tags to organise documents, for example returns or shipping. Send tags as a JSON array of up to 5 different lowercase words, each 1 to 24 letters (a to z). With a file upload, send the same JSON array in a part named tags. Tags appear in every document view; documents without tags return [].

Set tags when creating or replacing content. Leaving tags out keeps them on replacement; [] clears them. To edit only tags, send {"tags": ["returns", "shipping"]} to PUT /api/v1/documents/{id}/tags. This keeps the source, text and approval status. On the dashboard, add tags with a document or choose Edit tags, then filter by tag and by live, waiting for approval, unpublished or not live. A document with a waiting replacement appears in both Live and Waiting for approval.

Web page documents

  • Daily check. A job runs every hour and checks website documents not checked in the last 24 hours, in batches of 200, five at a time, until all due pages are checked. ETag and Last-Modified stamps let an unchanged site answer 304 without downloading its content. Without usable stamps, PCIFIC downloads the page and compares a content fingerprint before converting or processing it. Unchanged content is never reprocessed. Changed text makes a new version, which follows your review mode.
  • Refresh now. Use Refresh now beside a website document on the dashboard, or POST /api/v1/documents/{id}/refresh to check it straight away. Each document allows one manual attempt per minute, including failed attempts. A sooner attempt returns 429 DOCUMENT_REFRESH_TOO_SOON with a next step. The answer's changed says whether a new version was made. Only documents added from a web address can be refreshed.
  • lastCheck.at shows when the website was last checked, including an unchanged page or a failed check. lastChangedAt shows when changed text was last saved, including a version waiting for approval. With approve first, the old approved text keeps answering until you approve the waiting update on the dashboard.
  • When a read fails, the last good version keeps answering. The failure is saved on the document as lastCheck {at, ok: false, error, tryThis}, and shown on the dashboard.
Every documents address
AddressWhat it does
GET /api/v1/documentsEvery document, and limits: {documents: {used, max}, characters: {used, max}}.
POST /api/v1/documentsAdd one. Answers 201 with the document and warnings.
GET /api/v1/documents/{id}One document with its sections (the live version's, or the waiting one's if nothing is live) and its versions.
PUT /api/v1/documents/{id}/contentReplace its content with new text, a web address or a file. title is optional and keeps the old one. There is no PATCH: to rename a document, send its content again with a new title.
PUT /api/v1/documents/{id}/tagsSet tags without replacing content. Send {"tags": ["returns"]}, or {"tags": []} to clear them.
POST /api/v1/documents/{id}/refreshRead a web page document now.
POST /api/v1/documents/{id}/unpublishStop using it in answers, keeping its id and all saved versions.
POST /api/v1/documents/{id}/publishPublish again with its same id and last approved text. Waiting versions still need approval.
GET /api/v1/documents/{id}/versions/{versionId}One version's full text (markdown) and sections.
POST /api/v1/documents/{id}/versions/{versionId}Approve or reject a waiting version. Dashboard only: every API key is refused with 403.
DELETE /api/v1/documents/{id}Delete a document and every version of it.
A version in a document's versions list
FieldTypeRequiredWhat it is
idstringYesThe version.
statusstringYeslive, waiting, rejected or replaced.
createdAtstringYesWhen it was made.
charactersintegerYesIts length once converted to text.
approvedAtstringYesWhen it was approved, in UTC ending in Z. null if never approved or the earlier approval time was not recorded.
approvedByobjectYes{name, role} of the owner or admin who approved it, or null for an automatic approval.
approvedBy.namestringYesThe name of the person who approved it, or Former member when they have left the business.
approvedBy.rolestringYesTheir role when they approved it, such as owner or admin. null when it was not recorded.

Settings

GET and PUT /api/v1/ask-pcific/settings. A PUT changes only the fields you send. null clears fallbackMessage and supportLink; voice: null uses your shop voice. A live key can read these but never change them: use a test key with the settings permission, or the dashboard. The full list of every tool's settings is on the Shop configuration page.

Ask PCIFIC settings
FieldTypeRequiredWhat it is
enabledbooleanNofalse refuses every question with ASK_TURNED_OFF. Default true.
webSearchbooleanNoWhether the AI may search the web for general facts. Default true. false limits its supplied sources to your documents and the item.
reviewModestringNoautomatic (the default) puts a changed document live at once. approve_first holds each new version until an owner or admin approves it. Only an owner or admin can change this setting on the dashboard Documents page; API keys cannot change it.
fallbackMessagestringNoWhat a not_covered answer says, up to 500 characters. GET shows the standard message when you have not set one.
supportLinkstringNoAn https:// or mailto: link, up to 2,000 characters. Sent back with a not_covered answer.
voicestringNoAsk PCIFIC's voice: standard, warm, upbeat, formal, concise or reassuring. null uses your shop's voice.
keepChatsbooleanNoWhether a chat is kept so follow-up questions work. Default true. false means each question stands alone and nothing about the chat is stored.
Set a support link
curl -X PUT https://business.pcific.ai/api/v1/ask-pcific/settings \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"supportLink":"https://example.com/help"}'
Response, 200
{
  "enabled": true,
  "webSearch": true,
  "reviewMode": "approve_first",
  "fallbackMessage": "I couldn't find the answer to that in our information. Please contact our support team.",
  "supportLink": "https://example.com/help",
  "voice": null,
  "keepChats": true,
  "warnings": []
}

Where the listing comes from

The listing always comes from your own systems, never from the customer's page. Anything on a page can be edited in the customer's browser, so a question box that reads the listing from the page would let anyone get an answer about a price or condition you never set. Set up item lookup once and send only the item's id with each question. PCIFIC reads the listing from your own listings address at the moment the customer asks, so the answer matches what the customer sees, and PCIFIC never stores your listings. Your address answers as it already does, and every field it returns reaches the AI exactly as you named it. If your server sends the item's details with the question instead, read them from your own system at that moment, never from the customer's page.

Item lookup

With item lookup you give PCIFIC an address of yours that answers one item as JSON, and then you send the item id and optional buyer.accountId. The lookup receives buyerAccountId as a query parameter, for example /items/coat-8841?buyerAccountId=opaque-buyer-1. PCIFIC fetches the current details itself, so they are always up to date and the customer cannot change them. The AI can also look up another item by its id when the customer names one.

Set the address
curl -X PUT https://business.pcific.ai/api/v1/ask-pcific/item-source \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.example.com/items/{id}","headerName":"Authorization","headerValue":"Bearer your-items-api-key"}'
Response, 200
{
  "url": "https://api.example.com/items/{id}",
  "headerName": "Authorization"
}
Check it works
curl -X POST https://business.pcific.ai/api/v1/ask-pcific/item-source/test \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"coat-8841","buyer":{"accountId":"opaque-buyer-1"}}'
Response, 200
{
  "id": "coat-8841",
  "item": {
    "title": "Wool coat, navy, size M",
    "condition": "Used, good",
    "delivery": "Tracked, 2 to 4 working days",
    "reservation": "cannot confirm who it is reserved for"
  }
}
  • url must hold {id} where the item's id goes, and be a public https address. The id is made safe for a web address, and an id of . or .. is refused (ASK_ITEM_ID_NOT_ALLOWED).
  • The header is optional. headerName and headerValue go together or not at all. The value is stored encrypted and never shown again. A lookup that carries your header never follows a redirect to a different website.
  • A lookup waits at most 5 seconds and reads at most 256 KB. Your address must answer a JSON object, and 404 means the item does not exist.
  • PCIFIC fetches the item each time it is asked about, unless your address says its answer stays fresh for a while with a Cache-Control header, such as max-age=300 for five minutes. PCIFIC then reuses that answer until it expires, for at most 48 hours. no-store, no-cache or private means it is fetched every time. An answer for one buyer, with buyerAccountId, is only reused for that same buyer.
  • GET /api/v1/ask-pcific/item-source shows the address and header name, never the value. DELETE stops looking items up.
  • Item lookup is set up with the settings permission, on a test key.

Errors

Every error is JSON with error (what went wrong), code (a fixed name to branch on), tryThis (the next step) and sometimes problems (the exact fields at fault, as paths). 4xx means fix the request. 5xx means a problem on PCIFIC's side, so wait and try again.

Most errors also have a docs link to their own section on Ask PCIFIC errors, with the usual causes, how to fix it and a request that works. That page starts with the mistakes integrations make most often.

  • Refused straight away: a bad key, a bad body, a switched off tool, no documents, a wrong chat id and every item problem arrive as a normal JSON error with an HTTP status. Nothing is written. This is true when you stream too.
  • Failed later: ASK_MODEL_FAILED, ASK_EMPTY_ANSWER and ASK_TIMEOUT happen while the answer is being written. In a JSON request they come back as the response. In a stream the status is already 200, so they arrive as a final error event with the same error, code and tryThis.
  • Document, settings and item lookup problems are refused straight away on their own addresses.
  • Errors every address can return (UNAUTHORIZED, KEY_NOT_ALLOWED, BODY_TOO_LARGE, RATE_LIMITED, TEST_DAILY_CAP_REACHED, OUT_OF_CREDITS, INVALID_SETTING, BACKEND_UNAVAILABLE and the rest) are on the Errors, limits and retries page. If your business uses its own model, the errors on the Bring Your Own page can also appear.
Errors from a question
CodeHTTPWhy it happensHow to fix
ASK_QUESTION_MISSING400The question is missing or only spaces.Send the customer's question as text, like {"question": "Can I return this?"}.
ASK_QUESTION_INVALID400The question must be text.Send the customer's question as text, like {"question": "Can I return this?"}.
ASK_QUESTION_TOO_LONG400The question is over 1,500 characters.Shorten the question and send it again.
ASK_ACCOUNT_ID_INVALID400buyer has an unknown key, an account id has the wrong shape, or a lookup reservation holder is invalid; the error names the field and whether it is in the lookup response.Inside buyer send only accountId. Use opaque ids of 1 to 128 ASCII letters, digits, dots, colons, underscores or hyphens, never names or usernames. If the error names the item lookup response, correct reservedForAccountId there and test the lookup again.
ASK_PRICE_INVALID400A caller price or structured lookup price is malformed; the error names the price field and whether it is in the lookup response.For caller input, send item.price as {amount: 9575, currency: GBP}, using a nonnegative whole number in the smallest unit and a three letter currency code in capitals. For a lookup response, correct price in the configured lookup and test it again; caller item fields are ignored.
ASK_QUOTES_INVALID400quotes was sent but is not true or false.Send quotes: true to request a document quote, or leave quotes out.
MODEL_TIER_INVALID400modelTier is not standard or ultra-fast.Send modelTier: standard (the default) or ultra-fast, or leave it out.
INVALID_ITEM400Something in item has the wrong shape or is too long: item is not an object, item.id is not 1 to 128 characters of text or a number, type, title or url is too long, details has over 60 entries, or a detail is not one plain value.Read the message, which names the field. Send item as {"id": "abc-123", "title": "...", "details": {...}} with short plain values, or leave item out.
ASK_ITEM_ID_NOT_ALLOWED400The item id is . or .., which in a web address means a different folder, not an item.Send the item's real id, like "abc-123".
ASK_TURNED_OFF403Ask PCIFIC is switched off for this account.Switch it on in the dashboard, or send {"enabled": true} to PUT /api/v1/ask-pcific/settings.
ASK_CHATS_OFF400conversationId was sent, but the account keeps no chats (keepChats is false), so there is no chat to carry on.Leave conversationId out: each question is answered on its own. To keep chats, send {"keepChats": true} to PUT /api/v1/ask-pcific/settings.
ASK_CONVERSATION_NOT_FOUND404conversationId is not a chat of this account. It may be wrong, belong to another business, or be older than 30 days after its last question.Leave conversationId out to start a new chat.
ASK_ITEM_NOT_FOUND404Item lookup is set up, and your lookup address answered "not found" for this item id.Check the item id is right, or turn item lookup off and send the item's details in item.details instead.
ASK_NO_DOCUMENTS409The account has no live document to answer from. Either none was added, the only versions are waiting for approval, or the approved documents are unpublished.Add a document with POST /api/v1/documents or on the dashboard Documents page. If you approve changes first, ask an owner or admin to approve the waiting version there. For an unpublished approved document, use Publish again on Documents.
ASK_CHAT_TOO_FAST429This chat has asked 20 questions in the last minute, more than a person can type.Wait a minute and send the question again. If a real customer sees this, check your code sends each question once, not again on every retry or page refresh.
ASK_ITEM_LOOKUP_FAILED502Item lookup is set up, but your lookup address failed, took over 5 seconds, sent back over 256 KB, redirected to a different website, or did not answer a JSON object.Test the address with POST /api/v1/ask-pcific/item-source/test and check it answers one item as a JSON object.
ASK_ITEM_LOOKUP_NOT_CONFIGURED400item.id was sent but listing lookup is not set up for this business. The request is refused before any AI call or usage.Set up listing lookup in Ask PCIFIC settings, or leave item.id out and send the listing details in the request instead.
ASK_MODEL_FAILED502PCIFIC's AI could not finish the answer. This is a problem on PCIFIC's side.Send the question again in a few minutes. If it still fails, contact PCIFIC support.
AI_PROVIDERS_BLOCKED503Every AI model that could answer is from a provider PCIFIC has blocked for your business.Contact PCIFIC support to allow another AI provider for your business, then send the question again.
ASK_EMPTY_ANSWER502The AI finished without writing anything.Send the question again. If it keeps happening, contact PCIFIC support.
ASK_TIMEOUT504The answer took longer than 30 seconds and was stopped.Send the question again.
Errors from item lookup
CodeHTTPWhy it happensHow to fix
ASK_ACCOUNT_ID_INVALID400buyer has an unknown key, an account id has the wrong shape, or a lookup reservation holder is invalid; the error names the field and whether it is in the lookup response.Inside buyer send only accountId. Use opaque ids of 1 to 128 ASCII letters, digits, dots, colons, underscores or hyphens, never names or usernames. If the error names the item lookup response, correct reservedForAccountId there and test the lookup again.
ASK_PRICE_INVALID400A caller price or structured lookup price is malformed; the error names the price field and whether it is in the lookup response.For caller input, send item.price as {amount: 9575, currency: GBP}, using a nonnegative whole number in the smallest unit and a three letter currency code in capitals. For a lookup response, correct price in the configured lookup and test it again; caller item fields are ignored.
INVALID_ITEM_SOURCE400On PUT: url is missing, has no {id}, is over 2,000 characters, is not a public https address, or headerName and headerValue were not sent together. On test: id is missing.Put {id} where the item's id goes, like https://api.example.com/items/{id}. Send headerName and headerValue together, or neither.
ASK_ITEM_ID_NOT_ALLOWED400On test: the item id is . or .., which in a web address means a different folder, not an item.Send the item's real id, like "abc-123".
ASK_ITEM_NOT_FOUND404On test: your lookup address answered "not found" for this id.Check the item id is right, or send the item's details in item.details instead.
ASK_NO_ITEM_SOURCE409On test: item lookup is not set up.Set it with PUT /api/v1/ask-pcific/item-source.
ASK_ITEM_LOOKUP_FAILED502On test: your lookup address failed, took over 5 seconds, sent back over 256 KB, redirected to a different website, or did not answer a JSON object.Check the address answers one item as a JSON object, then test it again.
Errors from the documents addresses
CodeHTTPWhy it happensHow to fix
DOCUMENT_REFRESH_TOO_SOON429Refresh now was requested for this website document within the last minute.Wait one minute after the last refresh attempt, then try Refresh now again.
INVALID_JSON400The body is not a JSON object.Send a JSON object with the header "Content-Type: application/json".
INVALID_FIELD400A field has the wrong type or is too long. problems names each one.Fix each place named in problems, using its tryThis, then send the request again.
INVALID_DOCUMENT_TAGS400The document tags field is not an array of up to 5 different lowercase words, each 1 to 24 letters (a to z).Send tags as an array such as ["returns", "shipping"], or [] to clear them. For uploads, send the same JSON array in a part named tags.
DOCUMENT_TITLE_MISSING400You sent pasted text with no title.Add a "title" naming the document, for example "Returns policy".
DOCUMENT_CONTENT_MISSING400You sent neither text nor url, or both.Send the document's text as "text", or its web address as "url", or upload a file as multipart/form-data with a "file" field.
DOCUMENT_FILE_MISSING400The upload has no part named file.Send the document in a multipart/form-data field named "file".
INVALID_UPLOAD400The file upload could not be read.Send the file as multipart/form-data with the file in a field named "file".
DOCUMENT_TITLE_TOO_LONG400The title is over 200 characters.Use a short name for the document, for example "Returns policy".
DOCUMENT_ADDRESS_NOT_ALLOWED400The web address is not https, has a user name or password in it, or points at a private or local address.Use the public https:// address of the page, as it appears in a browser.
DOCUMENT_EMPTY400No text was found in the document, for example a scanned PDF, which is only a picture of text.Check you sent the right file or text. For a scanned PDF, copy its text in and send it as "text" instead.
DOCUMENT_NOT_HTML400An uploaded web page (.html or .htm) file has no HTML tags in it, so it is not really a web page.Upload the real web page, saved from your browser, or save the text as a .txt file and upload that instead.
DOCUMENT_LIMIT_REACHED409The business already has 50 documents.Delete a document you no longer need, or join related documents into one.
DOCUMENT_NOT_A_WEB_PAGE409You asked to refresh a document that is pasted text or a file.To change this document, send its new text or file to PUT /api/v1/documents/{id}/content.
DOCUMENT_UPLOAD_LIMIT429Your business has two document uploads or refreshes in progress, or its reserved input bytes are full. All shops and keys share this allowance. Busy background refreshes stay due for the next run.Try this document upload again in 20 seconds. Retry-After is 20.
DOCUMENT_UPLOAD_BUSY503PCIFIC's document upload capacity is full, or no PDF reader became available within two seconds.Try this document upload again in 20 seconds. Retry-After is 20.
DOCUMENT_UPLOAD_TIMEOUT408The document upload did not finish arriving within 20 seconds.Check your connection, then try the document upload again. Split a large file into smaller documents if needed.
DOCUMENT_FILE_TOO_LARGE413The file is larger than 10 MB.Split the document into smaller files, or paste its text instead.
DOCUMENT_TOO_LARGE413The document is over 300,000 characters once converted, or a Word file's text unpacks to over 20 MB.Split it into smaller documents, for example one per policy.
DOCUMENTS_FULL413The documents together would be over 2,000,000 characters.Delete documents Ask PCIFIC no longer needs, or shorten this one.
DOCUMENT_TYPE_NOT_SUPPORTED415The file is not a PDF, Word (.docx), web page (.html), Markdown (.md) or plain text (.txt) file.Send a PDF, Word (.docx), web page (.html), Markdown (.md) or plain text (.txt) file.
DOCUMENT_UNREADABLE422The file is damaged, password protected, text that is not UTF-8 or contains binary control characters, or a PDF that took too long or too much memory to read.Open the file to check it is not damaged or password protected, or copy its text in and send it as "text" instead.
DOCUMENT_FETCH_FAILED502The page could not be read: it does not exist, would not let PCIFIC in, was too slow, is not a web page, PDF or text file, or has almost no text.Check the address opens in a private browser window without signing in. If the page needs scripts to show its text, upload it as a file or paste its text instead.
DECISION_MISSING400The decision is missing or is not "approve" or "reject". Only reachable from the dashboard.The dashboard sends the decision for you. Pick Approve or Reject on the Documents page.
VERSION_NOT_WAITING409The version is not waiting for approval, or another person decided it a moment before. Only reachable from the dashboard.Only a version with status waiting can be decided. Open the document to see its waiting version, if it has one.
DOCUMENT_DECISION_NEEDS_DASHBOARD403An API key tried to approve or reject a waiting version. No API key, test or live, is allowed to.Ask an owner or admin of your business to approve or reject it on the Documents page of your PCIFIC dashboard.
NOT_FOUND404No document or version with this id for your business.Check the id. Ids from another business, or from before it was deleted, are not found.
Errors from dashboard Undo
CodeHTTPWhy it happensHow to fix
DOCUMENT_UNDO_UNAVAILABLE409The document's 10-second Undo window ended, or it is not awaiting removal.Reload Documents to check the list. If removed, add it again from your original text, file or web address.
Errors from unanswered questions
CodeHTTPWhy it happensHow to fix
INVALID_LIMIT400limit in the address is not a whole number from 1 to 200.Send a number from 1 to 200, like ?limit=50, or leave it out for the newest 50.

The unanswered list accepts limit from 1 to 200, default 50. Other values return 400 INVALID_LIMIT. Send a whole number in that range or leave limit out.

Limits

Ask PCIFIC limits
WhatLimitWhat happens past it
A question1 to 1,500 characters, and the whole body 16 KBASK_QUESTION_TOO_LONG, or BODY_TOO_LARGE for the body
item.id1 to 128 charactersINVALID_ITEM
item.type, item.title, item.url40, 300 and 2,000 charactersINVALID_ITEM
item.details60 entries, each a plain value of up to 2,000 charactersINVALID_ITEM
Time for one answer30 seconds, up to 4 rounds of tool use and 2 web searchesASK_TIMEOUT
Time the website waits for PCIFIC40 seconds for questions and for adding, replacing or refreshing a document, 15 for other callsBACKEND_UNAVAILABLE
A chatThe last 8 turns are used. Kept 30 days after its last questionA chat id after that is ASK_CONVERSATION_NOT_FOUND
Questions in one chat20 a minuteASK_CHAT_TOO_FAST
Unanswered questionsKept 30 days. limit 1 to 200, default 50Older ones are deleted
Documents50 per businessDOCUMENT_LIMIT_REACHED
One document300,000 characters once convertedDOCUMENT_TOO_LARGE
All documents together2,000,000 charactersDOCUMENTS_FULL
A file10 MBDOCUMENT_FILE_TOO_LARGE
A Word file's text once unpacked20 MBDOCUMENT_TOO_LARGE
A title200 charactersDOCUMENT_TITLE_TOO_LONG
Versions kept per documentThe live one, a waiting one and the newest 5Older versions are removed
fallbackMessage, supportLink500 and 2,000 charactersINVALID_SETTING
Item lookup5 seconds and 256 KB per itemASK_ITEM_LOOKUP_FAILED
Web search2 searches per answer, top 3 pages, each cut to 8,000 charactersThe AI answers with what it has

The limits that apply to every address, such as requests a minute, are on the Errors, limits and retries page.

Words used on this page

  • Item: whatever the customer is asking about, such as a listing, product, policy, property or booking.
  • Document: a piece of your own writing Ask PCIFIC answers from, such as a returns policy.
  • Version: one saved state of a document. Every change makes a new one.
  • Live and waiting: a live version answers questions. A waiting version is held until an owner or admin approves it.
  • Section: a part of a document that starts at a heading. Tags such as d1.2 mean document 1, section 2.
  • Source: where a fact came from: a document section, the item or a web page.
  • Quote: the document's own words, checked against the document before they are sent.
  • Chat: a run of questions with the same conversationId, so a follow-up question makes sense.
  • Fallback message: what a customer sees when nothing you wrote covers their question.
  • Markdown: plain text where a line starting with # is a heading.
  • SSE (server-sent events): a way for a server to send a reply in pieces over one connection.
  • https: a web address that starts with https://, the secure kind.