Quickstart: the API

Before you startCopy Anchor Link

• A ByteRover team with one drive. See Create a team and a drive.
• An API key with the scope Read and write. A team owner or admin can create one under Team > API keys with Create key. The dialog starts at the scope Search, which can't add files, so choose Read and write. See Authentication and API keys.

Export the key in your shell:

export BYTEROVER_API_KEY="brv_..."

1. Find your driveCopy Anchor Link

A key reaches either every shared drive of the team, including ones made later, or only the shared drives chosen for it. It never reaches anyone's My Drive, so put the files your key should search in a shared drive. The dialog starts at All shared drives. List the drives your key reaches and note the id of one. The cURL examples below use the sample ID drv_4h7k2m9q8r1t5v6w3x0y, so replace it with yours.

curl https://byterover.ai/api/v1/drives \
  -H "Authorization: Bearer $BYTEROVER_API_KEY"

2. Add a fileCopy Anchor Link

A small text file can go in a single request. PDFs, Office files and anything larger than 256 KiB go through an upload instead; see Upload files.

curl -X PUT https://byterover.ai/api/v1/drives/drv_4h7k2m9q8r1t5v6w3x0y/documents/by-path \
  -H "Authorization: Bearer $BYTEROVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/policies/customer-refund-policy.md",
    "text": "# Refunds\n\n## European Union\n\nCustomers in the European Union may cancel an order within 14 days of delivery and receive a full refund."
  }'

The response contains the document and an operation, which tracks the work of making the file searchable. Poll the operation until its status is done.

curl https://byterover.ai/api/v1/operations/op_3g6j9m2p5s8v1y4b7e0h \
  -H "Authorization: Bearer $BYTEROVER_API_KEY"

3. SearchCopy Anchor Link

Send the question, the drives to search and the effort. effort has no default; medium suits most questions.

curl https://byterover.ai/api/v1/search \
  -H "Authorization: Bearer $BYTEROVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Which policy section covers EU refunds?",
    "drive_ids": ["drv_4h7k2m9q8r1t5v6w3x0y"],
    "effort": "medium"
  }'

{
  "search_id": "srch_8f2k1m0q7r3t",
  "results": [
    {
      "passage_id": "psg_2c9d",
      "drive_id": "drv_4h7k2m9q8r1t5v6w3x0y",
      "document_id": "doc_7n4p1s8v2x5z9b3d6f0h",
      "revision": 1,
      "text": "Customers in the European Union may cancel an order within 14 days of delivery and receive a full refund.",
      "score": 0.94,
      "start_byte": 30,
      "end_byte": 135,
      "location": {
        "heading_path": ["Refunds", "European Union"],
        "before": "",
        "after": ""
      }
    }
  ],
  "effort": "medium",
  "search_ms": 812
}

Each result is a passage. Its location gives the headings above it, plus the page, slide or sheet when the file has them. Show this to your users so they can check the source.

4. Handle a question with no answerCopy Anchor Link

Search ranks passages; it doesn't decide whether they answer the question. Ask a question the file doesn't answer, such as "Is there a policy on drone inspections?", and you can still get the passages nearest to the subject. The list is empty, with status 200, only when nothing in the drive comes close.

The API returns passages only. To give your users a written answer, pass the passages to your own model and instruct it to say the files don't answer the question when no passage does. Don't let the model fill in from its own knowledge. A cited answer written by ByteRover, with a clear "not found", is in the app: see Ask a question.

NextCopy Anchor Link

• Upload files: PDF and Office files, and files up to 1 GB.
• Search: folders, tags, dates and file types.
• Errors and retries: every error code and how to handle it.
• API reference: every operation in full.