curl --request GET \
--url https://app.withrealm.com/api/external/alpha/documents/{data_source_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.withrealm.com/api/external/alpha/documents/{data_source_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.withrealm.com/api/external/alpha/documents/{data_source_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.withrealm.com/api/external/alpha/documents/{data_source_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://app.withrealm.com/api/external/alpha/documents/{data_source_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.withrealm.com/api/external/alpha/documents/{data_source_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"documents": [
{
"id": "doc_42",
"title": "Getting started with Realm",
"content": "# Getting started\n\nWelcome to Realm.",
"contentType": "markdown",
"url": "https://docs.example.com/getting-started",
"meta": {
"category": "guide"
},
"readAccess": [
"alice@example.com"
],
"verified": true
}
]
}{
"error": "<string>",
"details": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}List documents for a connector
Retrieve documents for a specific API Connector. This endpoint requires a Data Source ID. To get started:
- Go to the API Connectors page
- Create a new API Connector
- Copy the data source ID from the connector details page
- Use this ID in the path parameter
Pagination
The endpoint uses cursor-based pagination to handle large result sets efficiently. Here’s how it works:
- First Request: Make a request without a cursor to get the first page of results
- Subsequent Requests: Use the
nextCursorfrom the previous response to get the next page - Cursor Format: The cursor is a string containing digits only.
- End of Results: When
nextCursorisundefined, you’ve reached the end of the results
Example pagination flow:
- First request:
GET /documents/int_21XZai6JGvd1111J→ Returns first page withnextCursor - Next request:
GET /documents/int_21XZai6JGvd1111J?cursor=456→ Returns next page - Continue until
nextCursorisundefined
Field Selection
By default, only document IDs are returned. Use the fields parameter to request additional fields:
- Available fields: id, title, content, content_type, url, document_created_at, document_updated_at, meta
- Example:
fields=id,title,content
Rate Limits
600 requests per minute.
curl --request GET \
--url https://app.withrealm.com/api/external/alpha/documents/{data_source_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.withrealm.com/api/external/alpha/documents/{data_source_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.withrealm.com/api/external/alpha/documents/{data_source_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.withrealm.com/api/external/alpha/documents/{data_source_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://app.withrealm.com/api/external/alpha/documents/{data_source_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.withrealm.com/api/external/alpha/documents/{data_source_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"documents": [
{
"id": "doc_42",
"title": "Getting started with Realm",
"content": "# Getting started\n\nWelcome to Realm.",
"contentType": "markdown",
"url": "https://docs.example.com/getting-started",
"meta": {
"category": "guide"
},
"readAccess": [
"alice@example.com"
],
"verified": true
}
]
}{
"error": "<string>",
"details": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}Pagination
The endpoint uses cursor-based pagination. By default, only document IDs are returned. Use thefields parameter to request additional fields like title, content, url, and meta.
- Make a request without a cursor to get the first page of results
- Use the
nextCursorfrom the response to get the next page - Continue until
nextCursoris not present
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
ID of the custom API data source.
Query Parameters
Comma-separated list of fields to return. If not provided, only document IDs are returned.
id, title, content, content_type, url, document_created_at, document_updated_at, meta "id,title,content"
Cursor for pagination. Required for fetching results beyond the first 100 documents.
^\d+$Number of documents to return per page. Defaults to 20, maximum 100.
1 <= x <= 100Response
Success
Hide child attributes
Hide child attributes
markdown, text, html Optional unique identifier for the document. We enforce uniqueness in our end. If not provided, a UUID will be generated automatically and returned in the response. Must be alphanumeric and can include underscores and hyphens. The order of the documents in the response is the same as the order of the documents in the request, so you can match any generated IDs.
^[a-zA-Z0-9_-]+$UTC timestamp in ISO 8601 format (e.g. '2024-03-20T10:00:00Z')
UTC timestamp in ISO 8601 format (e.g. '2024-03-20T10:00:00Z')
Email addresses of the users that have read access to the document. If not provided, the document can be seen by anyone in Realm. Cannot be an empty array — omit the field instead.
1When true, marks this document as verified for this upsert. Send true on every upsert while the source system still treats it as authoritative; omitting it or sending false stops asserting source verification.

