Skip to content
Talki DevelopersBeta

Discover a site's pages

POST
/v1/documents/discover
curl --fail-with-body -X POST 'https://api.talki.it/v1/documents/discover' \
  -H "Authorization: Bearer $TALKI_API_KEY" \
  -H "Idempotency-Key: discover-bellini" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://www.example.com"}'

Look for the pages of the site at url, from its sitemap or its links, to choose the pages of an import. Imports nothing. max_pages is how many one import may read on the account’s plan. An address that is not public http or https, or any field besides url, is refused (invalid_parameter). Requires knowledge:write. Limited to 120 requests per minute per account (API key) or per installation (OAuth), and to 60 document writes per minute, shared by creating, replacing and updating documents and discovering a site’s pages.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters”
Talki-Version
string
Example
2026-10-01

Serve this one request at the given dated contract version instead of the credential’s pin. An unsupported value is refused with 400 unsupported_version, never downgraded.

Idempotency-Key
string
<= 255 characters

Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked Idempotency-Replayed: true, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a 400 asking for a different request (invalid_parameter, invalid_cursor, export_too_large, unknown_scenario, no_services_requested, stay_too_short, stay_too_long, stay_dates_invalid), a 415, a 409 request_conflict, document_not_ready or check_in_progress, a 412, a 429 and a 5xx.

Example
discover-bellini

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
DocumentDiscover

A site to look for pages in before importing it.

object
url
required
Url

The site’s address, http or https.

string
>= 1 characters <= 2048 characters
Example
{
  "url": "https://www.example.com"
}

Responses

Section titled “ Responses ”

200

Section titled “200”

Successful Response

Media typeapplication/json
DocumentDiscovery

The pages found on a site, to choose the pages of an import from, and how many one import may read on the account’s plan.

object
url
required
Url

The address looked at.

string
pages
required
Pages

The site’s pages found from its sitemap or its links, the address itself first.

Array<string>
max_pages
required
Any of:
integer
Examplegenerated
{
  "url": "example",
  "pages": [
    "example"
  ],
  "max_pages": 1
}

Headers

Section titled “Headers”
X-Request-Id
string

Identifier to include when contacting Talki support.

Talki-Version
string
Example
2026-10-01

The dated contract version this response was served at.

Idempotency-Replayed
string
Allowed values: true

true when this response was replayed from a prior request with the same key.

400

Section titled “400”

A parameter, cursor, body field, or required idempotency key is invalid, or Talki-Version names an unsupported version (unsupported_version).

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.

string
message
required
string
request_id
required
string
Example
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_parameter",
    "message": "One or more request values are invalid.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

401

Section titled “401”

The credential is missing, malformed, expired, revoked, or unknown.

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.

string
message
required
string
request_id
required
string
Example
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credentials",
    "message": "The supplied API credential is invalid.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

402

Section titled “402”

The account does not have an active subscription.

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.

string
message
required
string
request_id
required
string
Example
{
  "error": {
    "type": "permission_error",
    "code": "subscription_inactive",
    "message": "This account does not have an active subscription.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

403

Section titled “403”

The account or credential may not perform this request.

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.

string
message
required
string
request_id
required
string
Example
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This credential does not have the required scope.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

409

Section titled “409”

The write conflicts with current state or a previous idempotency key use.

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.

string
message
required
string
request_id
required
string
Example
{
  "error": {
    "type": "conflict",
    "code": "idempotency_key_reuse",
    "message": "This Idempotency-Key was already used for a different request.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

429

Section titled “429”

The account or installation exceeded its request rate (rate_limit_exceeded), or the calling address did (ip_rate_limited).

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.

string
message
required
string
request_id
required
string
Example
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the interval in Retry-After.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

Retry-After
integer

Seconds to wait before retrying.

X-RateLimit-Limit
string

The budget of the window that was exceeded. Absent on ip_rate_limited.

X-RateLimit-Remaining
integer

Requests left in the window. Absent on ip_rate_limited.

X-RateLimit-Reset
integer

When the window resets, in Unix seconds. Absent on ip_rate_limited.

500

Section titled “500”

An unexpected error occurred.

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.

string
message
required
string
request_id
required
string
Example
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred. Quote the request_id when reporting it.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

502

Section titled “502”

The site could not be read (api_error). Check the address, or retry later.

Media typeapplication/json

Every error answer has this shape.

object
error
required

The error itself. Branch on code; message is for people.

object
type
required
string
Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error
code
required

Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.

string
message
required
string
request_id
required
string
Example
{
  "error": {
    "type": "api_error",
    "code": "api_error",
    "message": "The site could not be read. Check the address, or retry later.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.