{"name":"sharing-tool","description":"Collaborative document runtime for humans and bring-your-own agents over HTTP.","version":"1.0.0","protocol":"sharing-tool-agent-v1","documentation":"https://share.appcortex.com/agent-docs","schemas":{"openapi":"https://share.appcortex.com/openapi.json","version":"3.1.0","dialect":"https://json-schema.org/draft/2020-12/schema"},"authentication":{"create":{"header":"X-Create-Key"},"document":{"preferred":"Authorization: Bearer <token>","also":["x-share-token","query token"]}},"capabilities":["docs.create","docs.agent-bootstrap","docs.state","docs.snapshot","docs.snapshot.compact","docs.snapshot.section","docs.search","docs.export.markdown","docs.edit.v2","docs.edit.table-cell","docs.events","docs.comments","docs.presence","docs.collab-sessions","docs.revoke","docs.delete"],"links":{"healthz":"https://share.appcortex.com/healthz","create":"https://share.appcortex.com/v1/docs","agentDocs":"https://share.appcortex.com/agent-docs","openapi":"https://share.appcortex.com/openapi.json","wellKnown":"https://share.appcortex.com/.well-known/agent.json","humanCreate":"https://share.appcortex.com/","waitlist":"https://share.appcortex.com/v1/waitlist","humanEditorTemplate":"https://share.appcortex.com/d/{slug}#token={accessToken}","agentInviteTemplate":"https://share.appcortex.com/agent/join/{slug}#token={accessToken}","markdownExportTemplate":"https://share.appcortex.com/v1/docs/{slug}/export?format=markdown"},"reads":{"snapshot":"/v1/docs/{slug}/snapshot","views":["full","outline","blocks","context","section","search"],"compactViews":{"outline":"?view=outline","blocks":"?view=blocks&ids={commaSeparatedBlockIds}","context":"?view=context&anchor={blockId}&before=2&after=2","section":"?view=section&heading={headingBlockId}","search":"?view=search&q={literalQuery}"},"contextLimitPerSide":20,"compactResponsesInclude":["revision","accessEpoch","baseToken"],"export":{"route":"/v1/docs/{slug}/export?format=markdown","contentType":"text/markdown; charset=utf-8","disposition":"attachment","source":"latest authoritative live document projection","excludes":["comments","suggestions","presence","events"]},"section":{"boundary":"selected heading through the block before the next heading of equal or higher level","bounds":"zero-based startIndex and exclusive endIndexExclusive","metadata":["headingId","headingLevel","totalBlocks"],"errors":{"HEADING_NOT_FOUND":"refresh outline and select an existing heading ID","BLOCK_NOT_HEADING":"select a heading ID from the outline"}},"completeBlocks":{"commentsRequired":true,"association":"comment.anchor.blockId equals block.id","order":["createdAt","id"],"includesOrphaned":true,"noComments":[],"excludedViews":["outline","truncated search placeholders"]},"search":{"matching":"case-insensitive literal substring","defaultLimit":20,"maxLimit":100,"defaultMaxBytes":65536,"maxMaxBytes":262144,"maxMatchPositionsPerBlock":25,"byteBudgetIncludes":"complete embedded comment objects","truncation":"whole blocks/comments only; placeholders retain view=blocks fetch pointer","pagination":"nextCursor/hasMore at matching block boundaries"}},"edit":{"concurrency":"baseToken OCC (mt1:sha256); same-kind replace_text-only or replace_table_cell-only batches may use a stale baseToken when every target precondition still holds","idempotencyHeader":"Idempotency-Key","freshnessMatrix":{"insert_after":{"freshness":"current_global_base","staleBaseToken":"rejected","staleError":"CONFLICT","recoveryAction":"refresh_full_snapshot_and_rebase"},"insert_before":{"freshness":"current_global_base","staleBaseToken":"rejected","staleError":"CONFLICT","recoveryAction":"refresh_full_snapshot_and_rebase"},"replace_block":{"freshness":"current_global_base","staleBaseToken":"rejected","staleError":"CONFLICT","recoveryAction":"refresh_full_snapshot_and_rebase"},"replace_text":{"freshness":"guarded_target","staleBaseToken":"allowed_in_replace_text_only_batch","precondition":"oldText and optional occurrence must match authoritative target","staleErrors":["TARGET_CHANGED","TARGET_AMBIGUOUS","TARGET_BLOCK_NOT_FOUND"]},"replace_table_cell":{"freshness":"guarded_target","staleBaseToken":"allowed_in_replace_table_cell_only_batch","precondition":"oldText must exactly match the authoritative cell at blockId and cell coordinates","staleErrors":["TABLE_CELL_CHANGED","TABLE_CELL_OUT_OF_BOUNDS","TABLE_CELL_TARGET_INVALID","TARGET_BLOCK_NOT_FOUND"]},"delete_block":{"freshness":"current_global_base","staleBaseToken":"rejected","staleError":"CONFLICT","recoveryAction":"refresh_full_snapshot_and_rebase"}},"mixedBatch":{"freshness":"current_global_base","staleError":"CONFLICT","recoveryAction":"refresh_full_snapshot_and_rebase"},"guardedBatchFailures":{"error":"GUARDED_EDIT_FAILED","operationIndexBase":0,"reports":"all detected guarded target failures","atomic":true,"idempotentReplay":true},"recovery":{"CONFLICT":{"action":"refresh_full_snapshot_and_rebase","snapshot":{"view":"full"},"retry":{"baseToken":"snapshot.baseToken","idempotencyKey":"new"}},"GUARDED_EDIT_FAILED":{"action":"resolve_all_guarded_failures_and_retry","atomic":true,"retry":{"baseToken":"refreshedSnapshot.baseToken","idempotencyKey":"new"}},"TARGET_CHANGED":{"action":"inspect_target_and_update_precondition","snapshot":{"view":"blocks","ids":["{blockId}"]},"retry":{"batch":"replace_text_only","baseToken":"snapshot.baseToken","idempotencyKey":"new"}},"TARGET_AMBIGUOUS":{"action":"inspect_target_and_set_occurrence","snapshot":{"view":"blocks","ids":["{blockId}"]},"retry":{"batch":"replace_text_only","baseToken":"snapshot.baseToken","idempotencyKey":"new"}},"TARGET_BLOCK_NOT_FOUND":{"action":"refresh_full_snapshot_and_retarget","snapshot":{"view":"full"},"retry":{"batch":"same_guarded_operation_only","allowedBatches":["replace_text_only","replace_table_cell_only"],"baseToken":"snapshot.baseToken","idempotencyKey":"new"}},"TABLE_CELL_CHANGED":{"action":"inspect_table_cell_and_update_precondition","snapshot":{"view":"blocks","ids":["{blockId}"]},"retry":{"batch":"replace_table_cell_only","baseToken":"snapshot.baseToken","idempotencyKey":"new"}},"TABLE_CELL_OUT_OF_BOUNDS":{"action":"inspect_table_dimensions_and_retarget","snapshot":{"view":"blocks","ids":["{blockId}"]},"retry":{"batch":"replace_table_cell_only","baseToken":"snapshot.baseToken","idempotencyKey":"new"}},"TABLE_CELL_TARGET_INVALID":{"action":"inspect_table_block_and_retarget","snapshot":{"view":"blocks","ids":["{blockId}"]},"retry":{"batch":"replace_table_cell_only","baseToken":"snapshot.baseToken","idempotencyKey":"new"}},"IDEMPOTENCY_KEY_REUSED":{"action":"use_new_idempotency_key","retry":{"idempotencyKey":"new"}}},"operations":["insert_after","insert_before","replace_block","replace_text","replace_table_cell","delete_block"],"guardedOperations":{"replace_text":{"matchText":"rendered block text without inline markdown delimiters","occurrence":"optional positive 1-based integer"},"replace_table_cell":{"matchText":"exact oldText at the explicit cell coordinate","coordinateBase":0}},"table":{"textField":"empty compatibility sentinel; not editable content","cellAddressing":"supported","replaceText":"unsupported; use replace_table_cell","cellOperation":"replace_table_cell","coordinates":{"header":"{ section: header, column: zero-based }","body":"{ section: body, row: zero-based, column: zero-based }"},"expectedContentField":"oldText","cellValue":"single-line string; literal pipes are accepted","fallbackWholeTableOperation":"replace_block","errors":["INVALID_TABLE_CELL_COORDINATES","INVALID_TABLE_CELL_VALUE","TABLE_CELL_TARGET_INVALID","TABLE_CELL_OUT_OF_BOUNDS","TABLE_CELL_CHANGED","TARGET_BLOCK_NOT_FOUND"],"replaceTextUnsupportedError":"TABLE_TEXT_UNSUPPORTED"},"list":{"level":"zero-based nesting depth","mixedTypes":true,"parentRule":"a level N item requires a preceding item at level N-1 in the same contiguous list sequence","emptyItems":"unsupported","invalidError":"INVALID_LIST_STRUCTURE"},"successBlocks":"complete blocks with embedded comments arrays","conflictStatus":409},"comments":{"anchorModes":["quote","block_range"],"blockRange":{"fields":["blockId","from","to","quote"],"offsets":"zero-based UTF-16 offsets into snapshot blocks[].text","quote":"exact expected substring; all evidence must agree"},"responseAnchor":"comment.anchor retains structured block-range evidence","embeddedInBlocks":"structured comments appear on complete blocks; legacy/unassociated marks remain in state","table":{"supportedAnchorMode":"quote","blockRange":"unsupported"},"hardDelete":{"route":"DELETE /v1/docs/:slug/comments/:commentId","idempotencyHeader":"Idempotency-Key","event":"comment.deleted"},"errors":["INVALID_ANCHOR","ANCHOR_BLOCK_NOT_FOUND","ANCHOR_TARGET_CHANGED","ANCHOR_AMBIGUOUS","ANCHOR_NOT_FOUND","TABLE_BLOCK_RANGE_UNSUPPORTED"]},"idempotency":{"header":"Idempotency-Key","scope":"document + mutation route","requestBinding":"canonical semantic request fingerprint","mismatch":{"status":409,"error":"IDEMPOTENCY_KEY_REUSED"},"concurrentRetries":"serialized; one mutation applies"},"events":{"cursor":"events[].id; pass the last consumed id as after","pagination":{"defaultLimit":100,"maxLimit":500},"longPolling":{"parameter":"waitMs","maxWaitMs":30000},"responseMetadata":["nextCursor","hasMore"],"eventMetadata":["actor","changedBlockIds"]},"presence":{"optIn":true,"readsDoNotImplyPresence":true,"join":{"requiresExplicitPost":true,"route":"POST /v1/docs/{slug}/presence","successStatus":200},"refresh":{"route":"repeat join POST","deadlineField":"expiresAt"},"leave":{"route":"POST /v1/docs/{slug}/presence","status":"leave","fallback":"automatic lease expiry"},"agentIdHeader":"X-Agent-Id","optionalMetadata":["intent","targetBlockIds"],"maxIntentLength":160,"maxTargetBlocks":20,"ttlSeconds":{"defaultSeconds":60,"minSeconds":5,"maxSeconds":300},"leaseRefresh":"POST presence again before expiresAt","errors":["INVALID_PRESENCE","PRESENCE_TARGET_NOT_FOUND"]},"notes":["Share links are secrets.","Task instructions stay out of band (chat/skill session).","No SDK or MCP required."]}