Message connections and knowledge reading objects

Ingress connections are workspace management resources. Runtime knowledge APIs are for the current agent task and require its identity, source scope, and short-lived authorization.

Connection and input identifiers

Variable

Source

WORKSPACE_ID, AI_STUDIO_API_KEY

Workspace in the current environment and a personal access token with the required privileges.

AGENT_WORKSPACE_ID, AGENT_ID

Actual owning workspace and ID of the agent selected from the catalog.

AGENT_MODEL

Runtime model available to the current target; required explicitly for agent targets.

CONNECTION_ID

id from a creation response or the same target’s connection list.

ASSOCIATION_VERSION

association_version from the latest connection details.

CONFIG_VERSION

config_version from the latest connection details.

MANAGED_CREDENTIALS_FILE

JSON file containing credentials required to create the selected platform’s managed connection. Restrict access and do not write it to logs or the repository.

CALLBACK_URL

Full HTTPS callback URL for the deployment; its path matches callback_path in connection details.

The owning workspace must match the path and X-Workspace-ID. A team target belongs to that workspace. An agent target belongs to the current or system workspace. Use actual catalog values rather than inventing workspace identifiers.

Ingress connections

Field

Type

Description

id

string

Ingress connection ID.

workspace_id

string

Execution workspace.

target.kind

string

agent or team.

target.workspace_id

string

Workspace that owns the target.

target.id

string

Target identifier.

provider

string

Selected platform.

channel_type

string

Selected channel type.

receive_mode

string

managed_stream, callback, or mail_polling.

channel_instance_id

string

Independent channel instance referenced by callback/mail_polling.

provider_config

object

Readable nonsensitive platform configuration.

agent_model

string

Model selected for the agent target.

association_version

integer

Target association version.

config_version

integer

Current connection configuration version.

connected_by_user_id

string

User who established the connection.

enabled

boolean

Whether enabled.

account_identity

string

Associated platform account identity.

desired_state

string

enabled or disabled.

observed_state

string

State currently observed by the receiver.

last_receive_at

string

Last receive time; returned when present.

last_error_code

string

Most recent runtime error code; returned when present.

callback_path

string

Deployment-relative callback path in callback mode; returned when present.

created_at

string

Creation time.

updated_at

string

Update time.

starting/reconnecting means establishing or recovering a connection. For auth_failed/config_invalid, fix credentials or configuration first. connected describes only the connection layer; verify actual messages, target tasks, and replies. waiting_for_first_message waits for the first external input. stopped indicates stopped.

Creating managed_stream enables the connection and enters starting; mail_polling waits for input; callback starts disabled. A successful callback /test enables the connection and increments config_version; it is not a read without side effects.

Managed credentials

Platform combination

Required for creation

Required for update

wecom / wecom_ai_bot

bot_id、secret

secret

slack / slack_app

app_id, app_token, bot_token

app_token or bot_token; both may be updated

feishu / feishu_app

app_id、app_secret

app_secret

Slack App Tokens start with xapp- and Bot Tokens with xoxb-. Do not include fields from another platform. Do not resend the creation App ID/Bot ID during updates. Handle platform account identity separately from rotatable secrets.

Two successful HTTP response shapes for callback verification

Successful verification returns a connection object. If the provider channel test fails, HTTP 200 may instead return a test object containing ok:false, status, last_test_status, last_test_error, optional error classifications/suggestions, and last_tested_at. Do not check HTTP status alone or read this as a connection object.

Telegram verification registers the current full HTTPS Webhook URL. Other platform branches verify the channel instance; failures appear in a test object or error response. Managed and mail-polling modes do not use this verification operation.

WeCom QR authorization

The pending QR API response includes session_token, qr_url, and expires_at. Poll with the original token while retaining the same account, target, and workspace. authorized returns bot_id/secret but has not saved an actual ingress connection; call creation next. End the old session after expired and honor 429/Retry-After rather than polling indefinitely. Pass these tokens and secrets only to a protected client.

Task knowledge connections

Variable

Source

MOI_ENDPOINT

Product service prefix injected into the current task. Do not replace it with another environment or an address saved in the terminal.

MOI_API_KEY

Technical connection credential for the current task.

MOI_WORKSPACE_ID

Execution workspace of the current task.

MOI_RUNTIME_AUTHORIZATION

Complete short-lived authorization header value injected into the task; retain unchanged.

REQUEST_ID

Distinct ID generated for each new operation. Retain this ID and original input when replaying the same request.

KNOWLEDGE_QUERY

Effective retrieval text for the current question.

ARTIFACT_ID

Original artifact_id from retrieval/query within the same task.

CHUNK_ID

Original chunk_id of the selected text evidence.

FILE_ID

file_id of the same text evidence.

SEMANTIC_MODEL_ID

Actual integer model ID returned with the same evidence.

MARKDOWN_FILE_ID

Parsed-source location ID from evidence. Do not derive it from the original file ID.

TABLE_NAME

Table name allowed for the task by describe-tables.

KNOWLEDGE_SQL_FILE

Read-only SQL text file prepared from the schema read and the question.

CITATION_SOURCES_FILE

JSON array containing all sources actually used in the current answer.

These APIs do not accept a regular PAT in place of task identity or allow switching task, user, or role in the body. request_id must be 1–256 bytes, have no surrounding whitespace, and not start with audit:. Do not use a new ID to bypass replay checks for the same operation.

Knowledge results and read modes

Successful runtime knowledge HTTP envelopes use code=”OK”. data includes call_id, output, and optional failed/artifacts/metadata. failed=true is still a business failure. All output retains task evidence identity; do not reconstruct file, model, or artifact IDs from names.

Complete text retrieval chunks are stored in artifacts[].data.chunks. When reading, retain the same artifact_id and chunk_id/file_id/semantic_model_id. output may be a bounded view. A preview or truncated text cannot establish a complete-read proof.

Read mode

Input

Completion and continuation

Single evidence chunk

artifact_id, chunk_id, and file_id/semantic_model_id as needed; integer cursor

Original text in output.content; continue with the original next_cursor when has_more is true.

Evidence list

artifact_id without single-chunk selection; explicitly start with object cursor={item_index:0,content_offset:0}

output.items contains the page window. complete=true means finished; otherwise continue with object next_cursor.

Fixed artifact part

artifact_id, part_index

output.part and part_count. Do not combine with chunk, character pagination, or local-read proof fields.

Register a complete local read

Single-chunk identity and local_content_sha256, or local_reads array

Registered after the server verifies the original content digest. Do not combine with pagination parameters.

Parsed Markdown

markdown_file_id, integer cursor

output.content. Stop when next_cursor=0; there is no has_more.

Evidence character windows range from 1 to 8000; omitted/0 uses 2000. Cursors count Unicode characters, not UTF-8 bytes. Nonpositive Markdown windows use 8000, maximum 20000. Markdown and evidence windows have different defaults.

With artifact_id alone and no read mode, generic reads may instead return the artifact object and part_count. Do not assume evidence-list pagination was selected.

A local single-chunk read proof requires artifact_id/chunk_id and the complete content digest; file_id/semantic_model_id locate the content. Each local_reads item supplies this identity and digest. Do not combine the batch form with top-level single-chunk fields. Success registers a complete read of that task’s original chunk only, not the entire source or knowledge base.

Parsed source text is reconstructed from currently effective chunks. Persisted evidence artifacts and current parsed-source projections serve different purposes. The fact that current chunk reads reflect deletion/disabling does not imply every historical artifact is rewritten.

Retrieval and citations

Regular search requires valid keywords and max_hits greater than 0. source_page mode uses model ID, file ID, page size, and opaque cursor and cannot be combined with regular search fields. Stop according to output.source_page.has_more. Listing enabled indexed chunks by source is not semantic ranking and does not prove unindexed content is absent.

Image retrieval returns output.results, count, the applicable mode, and corresponding artifacts. Query image IDs and returned image-evidence identifiers are not interchangeable. API parameters do not accept model-internal query_visual or multi-image fields.

Structured queries allow read-only SELECT on tables permitted for the current task. Results include actual SQL, columns, rows, row count, truncation, and source artifacts. Omitting semantic_claims does not bypass mandatory semantic conditions saved by the server. Read schemas and constraints before querying and selecting sources.

cite submits the complete source set for the current answer. Text sources must retain at least type=rag_chunk, artifact_id, chunk_id, and original identity. Explicitly send sources:[] when there is no evidence. Check output.accepted. If not accepted, read the returned unread windows before selecting again. After acceptance, write the answer from the evidence.

Errors and environments

Ingress business success uses numeric code 0. Business errors use numeric code/message/details.reason, while admission may use string code/msg. Runtime knowledge usually uses string code/msg. Handle data.failed or output.accepted=false separately even under HTTP 200.

A capability list proves only declared implementation, not environment readiness. Callback verification and QR requests may call providers and require temporary accounts, controlled targets, and a cleanup plan. Do not reuse callbacks or task authorizations between environments.

Last updated on