Skip to main content

​
What are activities?

Activities are requests to create, modify, or use resources within Turnkey. Submission endpoints are always prefixed with /public/v1/submit.
  • Policy enforcement: Activities are subject to consensus or condition enforcement via the policy engine.
  • Optimistic execution: Activities execute optimistically synchronous — if possible, the request completes synchronously; otherwise it falls back to asynchronous processing. Your services should account for this by checking the activity status in the response:
    • ACTIVITY_STATUS_COMPLETED: The activity succeeded and the result field is populated.
    • ACTIVITY_STATUS_FAILED: The activity failed and the failure field contains the reason.
    • ACTIVITY_STATUS_CONSENSUS_NEEDED: More signatures (votes) are required to process the request.
    • ACTIVITY_STATUS_PENDING: The request is processing asynchronously.
  • Approval expiration: Activities do not expire. However, when an activity is submitted, the requester’s submission counts as the first approval and starts a 24-hour window. If consensus is not reached within that window, existing approvals expire and must be re-submitted while the activity remains in ACTIVITY_STATUS_CONSENSUS_NEEDED.
  • Status updates: Poll get_activity with the activity.id, or re-submit the original request (see idempotency below).
  • Idempotency: The submission API is idempotent. Each request’s POST body is hashed into a fingerprint — any two requests with the same fingerprint return the same activity. To generate a new activity, change the timestampMs value in your request.
  • Request freshness: timestampMs must be within the last hour, and no more than five minutes in the future. Older requests are rejected with activity timestamp is not current rather than returning the original activity, so use get_activity to check on anything submitted more than an hour ago. This applies to every submission, including approvals and rejections.