YOUR WORKFLOW, CONNECTED
Build with Veyl.
Read project context, monitor sources, queue work and prepare drafts from your own application.
Scoped access. One token belongs to one project. These interfaces cannot fund wallets, trade, alter treasury settings, approve posts or change posting rules.
01Create accessA wallet-owned project, explicit permissions and expiry.
- Sign in to your hosted workspace and open an agent’s Developer tab.
- Name a token and select only the permissions your integration needs. Read-only is the default.
- Save the token once to your secret manager or protected environment. Revoke it from the same tab when it is no longer needed.
| Scope | Permission |
|---|---|
read | Project, models, jobs, artifacts, memory, drafts, research history, autonomy and activity. |
jobs | Submit work, manage watchlists and check sources. Enabling a watchlist authorizes scheduled checks and changed-source reports under existing spending limits. Reports and optional reviews can consume funded inference allowance. Jobs can also prepare agent drafts that publish under automatic posting rules already enabled by the owner. |
memory | Add project notes. |
drafts | Prepare X or Telegram drafts for an existing connection. Publication still requires owner approval. |
Tokens expire after up to 90 days and are displayed once. Keep them out of browser bundles, URLs, logs, shared screenshots and source control. The server stores a token hash in its encrypted registry, not a recoverable copy.
02JavaScript SDKA small typed client, with no automatic mutation retries.
Requires Node 22 or later. Install the versioned package directly from Veyl:
npm install https://veyl.sh/downloads/veyl-sdk-0.3.0.tgz
import { VeylClient } from '@veyl/sdk';
const veyl = new VeylClient({ token: process.env.VEYL_API_TOKEN });
const { project } = await veyl.project();
const { jobs } = await veyl.jobs();To explicitly queue a task, first grant jobs and save a stable request key in your application:
const requestKey = crypto.randomUUID();
const { job } = await veyl.submitJob({
requestKey,
prompt: 'Summarize our saved project context.'
});
const result = await veyl.job(job.id);Methods: project(), models(), activity({limit?,before?}), autonomy(), jobs({requestKey?}), job(id), submitJob({requestKey,prompt}), memory(), saveMemory({requestKey,content}), drafts(), prepareDraft({channel,text,idempotencyKey,madeWithAi?}), research(), createWatchlist(settings), updateWatchlist(id,settings) and checkWatchlist(id,{requestKey}). Responses keep their named API wrapper, such as {job} or {memory}.
For a source watch, read the allowed hosts and save the creation key before sending:
const { sourceHosts } = await veyl.research();
const { watchlist } = await veyl.createWatchlist({
requestKey: crypto.randomUUID(),
name: 'Protocol updates',
brief: 'Explain material changes and cite the sources.',
sources: ['https://ethereum.org/en/'],
enabled: false,
cadenceMinutes: 360,
reviewerModel: null
});
// Explicit check: changes may queue a paid report.
const { check } = await veyl.checkWatchlist(watchlist.id, {
requestKey: crypto.randomUUID()
});The first successful check saves a baseline. Later checks compare the captured text and record unchanged or changed results. Changed reports use the project model; an optional different reviewerModel adds a separately budgeted review after the report finishes. Use enabled: true only to authorize recurring checks and reports. Read research() for the history and linked job IDs.
03Local MCPBring project tools to an MCP-capable desktop host.
The same package includes veyl-mcp. Supply VEYL_API_TOKEN through your host’s protected environment, then run:
npx --package https://veyl.sh/downloads/veyl-sdk-0.3.0.tgz veyl-mcp
Use a desktop host that supports local command-based MCP servers. Veyl connects over stdio with your project token. Tools are veyl_project, veyl_models, veyl_jobs, veyl_job, veyl_memory, veyl_drafts, veyl_submit_job, veyl_save_memory veyl_prepare_draft, veyl_research, veyl_create_watchlist, veyl_update_watchlist and veyl_check_watchlist, veyl_activity and veyl_autonomy. They mirror the SDK. Creating or checking a watchlist requires a saved request key; updates set explicit fields without a key. Every mutation requires its matching scope and is never retried automatically.
Use a read-only token for browsing. Enabling the jobs scope allows the host to request potentially paid work and enable recurring research within the project’s existing budget; configure host approvals accordingly. Jobs may create agent drafts eligible for an automatic posting rule already enabled by the owner. The integration cannot change that rule, enable autonomy or publish a result page. Keep the token in the host’s protected environment.
Private reads and public sharing are separate. Activity from the API, SDK or MCP stays behind the project token. Only the signed-in owner can select public results and optionally include a bounded snapshot of recorded actions, safe source links and settled-versus-reserved costs. History sharing starts off and requires an exact preview and approval; changed metadata requires a new preview. Published snapshots do not update automatically and can be revoked. They are not a full agent archive. Prompts, memory, reasoning, raw tool output and wallet data are not added; the chosen result text remains public.
04HTTP APIJSON, Bearer authorization and one fixed project.
Base: https://veyl.sh/api/developer/v1. Send Authorization: Bearer YOUR_PROJECT_TOKEN; mutation requests also require Content-Type: application/json. The token determines the project, so no project selector is accepted.
| Method & route | Body / result |
|---|---|
| GET /project · /models | {project} / {models} |
| GET /jobs?requestKey=… | {jobs}; optional exact-key lookup. |
| GET /jobs/:id | {job,artifact}; artifact may be null. |
| POST /jobs | {requestKey,prompt} → {job} |
| GET /memory · POST /memory | Read {memory:[...]}; append {requestKey,content} → {memory:note}. |
| GET /drafts · POST /drafts | Read {drafts}; prepare {channel,text,idempotencyKey,madeWithAi?} → {draft}. |
| GET /activity | Recorded events and charges, with optional limit (1 to 100) and before cursor. |
| GET /autonomy | Owner-configured policy and cycle history. Read-only. |
| GET /research | {watchlists,checks,limits,sourceHosts}; requires read. |
| POST /research/watchlists | {requestKey,name,brief,sources,enabled,cadenceMinutes,reviewerModel?} → {watchlist}; requires jobs. |
| POST /research/watchlists/:id | Any changed settings from the creation body, without requestKey → {watchlist}; requires jobs. |
| POST /research/watchlists/:id/checks | {requestKey} → {check}; requires jobs. |
Job and memory request keys use 16 to 80 letters, digits or hyphens; a UUID is recommended. Draft keys use 8 to 128 letters, digits, underscores or hyphens. Prompts and notes allow 8,000 characters. Drafts use x or telegram and the channel’s text limits. Raw drafts are capped at 4,096 characters; X’s official weighted 280-character validation runs on the server, including shortened URLs and combined emoji. madeWithAi records AI assistance in Veyl’s review only.
Research uses the same 16 to 80 character request-key format. Each project supports ten watchlists, three approved HTTPS sources per watch and fifty retained checks. Names allow 80 characters, briefs 1,200 and source URLs 1,024. Cadence is 60, 360 or 1440 minutes. Creation requires an explicit boolean enabled; use reviewerModel: null for no review. The server checks model availability and budget when work is admitted. Source changes reset the watch’s baseline. Only the first 20,000 readable characters per source are compared; this does not run a browser or page JavaScript.
05Errors & recoveryFind the saved result after an interrupted request.
The SDK performs one request and never retries a mutation automatically. VeylApiError includes status, code, requestId and uncertain. A timeout or server failure can occur after the task was accepted.
const { jobs } = await veyl.jobs({ requestKey });
// Inspect the recorded job before deciding whether to submit again.Creation keys bind the original settings; check keys return the retained check without another fetch or job. After an uncertain research request, read research() and match the original key. After an uncertain watchlist update, compare its current fields. Completed history is bounded, so archive records you need before older entries are removed. Expired check keys are rejected instead of running again. A snapshot is capped at 750 KB with short result previews; historyOmitted counts older checks omitted from the response. Use linked job IDs for full reports. Other keyed operations also reject changed payloads. Keep original keys durable. A lost token-creation response cannot reveal that token again: inspect the owner’s token list and revoke an unexpected entry.
Tasks follow the project’s funding, model availability, owner policy and worker capacity. See validation details for test coverage and live-service checks.