API reference

HTTP endpoints, request identity, responses, usage and observation events.

On this page

Authentication and base URL

Base URL: https://api.clone.is. Send Authorization: Bearer <app key> from your backend. Never embed the key in browser or mobile bundles. Download the OpenAPI contract for exact field types and response schemas.

Method	Endpoint	Purpose
POST	`/v1/predictions`	Complete a draft or predict the next prompt
POST	`/v1/predictions/{request_id}/cancel`	Cancel pending work for the authenticated subject
POST	`/v1/prediction-events`	Record observations, explicit feedback or task outcomes
POST	`/v1/prediction-feedback/clear`	Clear this app/user's feedback memory
GET	`/v1/usage`	App usage, billing model, remaining sandbox allowance and configured hard limit
POST	`/v1/connections`	Start optional user-authorized personalization
POST	`/v1/connections/exchange`	Exchange the one-time callback with PKCE and the same subject
POST	`/v1/connections/{connection_id}/revoke`	Revoke only this app/user connection

App keys do not manage company billing or grant access to arbitrary Clone accounts. The owner-only /v1/developer/apps API uses a verified owner session or account management token. Use the developer management reference.

Prediction fields

Field	Meaning
`request_id`	Stable identifier for one request and any replay of that exact body
`user_id`	Subject derived from your backend's authenticated session
`session_id`	Stable customer thread or workspace conversation
`mode`	`next_prompt` with empty draft, or `complete_draft` with nonempty draft
`draft`	`text` up to 8,000 characters and monotonic `revision`
`context_revision`	Change when relevant conversation, artifact, preferences or selection changes
`messages`	Up to 30 recent turns, each up to 8,000 characters; preserve `role` and `origin`
`artifact`	Optional `video`, `slides` or `other` with ID, revision, selection and a known text summary
`user_preferences`	Optional product-owned preferences, up to 4,000 characters
`connection_id`	Omit or null for product context; otherwise an explicitly authorized connection
`language`	Requested output language, default `auto`
`feedback_enabled`	Use scoped recent feedback, default `true`; set `false` to omit it

Large context is subject to token-budget validation. Do not erase the user's latest correction to fit the envelope. See the schema for exact limits.

Responses and idempotency

The result echoes request/session/draft/context/connection identity. feedback_revision identifies the feedback actually included, or is empty when none was included. usage.prediction_units is 0 or 1. Acceptance is valid only until expires_at; a retained replay receipt does not extend it. Result recovery is available for one hour. Never transform a timed-out paid request into a new ID automatically.

409 prediction_in_progress means the original ID is pending; 409 idempotency_conflict means its body or subject changed. 410 prediction_replay_expired ends result recovery. Terminal failed or canceled IDs do not execute again. Error and outage behavior.

Observation events

Send { "event_id": "event-001", "request_id": "first-prediction-001", "user_id": "your-authenticated-user", "kind": "presented" } to /v1/prediction-events. Kinds are presented, accepted, edited, dismissed, submitted, rejected, feedback, outcome. Keep the same event ID and body on retries. Events do not change billing.

Record submitted only after your host accepts the send. Automatic Clone mode prompts have message origin agent; they must not be counted as independently human-written preferences or manual Tab acceptance.

Explicit rejected or feedback evaluations and opted-in edited submissions can inform the next new prediction. Acceptance counts and task outcomes alone are not preference labels. Text collection is off by default: guidance and edited final_text require content_opt_in: true. Use outcome: "succeeded" or "failed" only after observing the host task result.

Memory is encrypted, limited to this app/user and the same connection grant, and expires after 30 days. Clear it with { "user_id": "your-authenticated-user" } at /v1/prediction-feedback/clear. Old requests cannot restore cleared memory; stale results using it return 409 feedback_context_cleared. See the SDK feedback guide for integration examples and exact limits. This context loop does not train model weights.

Python, without the SDK

import json, os, urllib.request

with open("prediction.json", encoding="utf-8") as source:
    payload = json.load(source)
request = urllib.request.Request(
    "https://api.clone.is/v1/predictions",
    data=json.dumps(payload).encode(),
    headers={"Authorization": "Bearer " + os.environ["CLONE_APP_KEY"],
             "Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(request, timeout=15) as response:
    result = json.load(response)
# Validate identity and expiry before presenting result["completion"].

Use your host's cancellation and concurrency limits in production. The API returns predictions; your application owns agent execution and permissions.

← All guides Composer SDK →