Skip to main content
POST
/
v1
/
phones
/
{phone_id}
/
open-url
Open URL
curl --request POST \
  --url https://api.example.com/v1/phones/{phone_id}/open-url

Documentation Index

Fetch the complete documentation index at: https://docs.tapkit.ai/llms.txt

Use this file to discover all available pages before exploring further.

Open a URL on the phone through the Use TapKit shortcut. TapKit enqueues an open_url shortcut action for the phone, then triggers the shortcut through the selected Mac. The shortcut fetches the pending action and opens the URL from the action payload.
This endpoint currently does not validate URLs. Send a full URL, including the scheme, such as https://www.apple.com.

​
Request

curl -X POST https://api.tapkit.ai/v1/phones/{phone_id}/open-url \
  -H "X-API-Key: joot_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.apple.com"}'
You can also authenticate with a bearer token: 
curl -X POST https://api.tapkit.ai/v1/phones/{phone_id}/open-url \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.apple.com"}'

​
Path Parameters

ParameterTypeDescription
phone_idstringThe phone identifier

​
Query Parameters

ParameterTypeDefaultDescription
asyncbooleanfalseReturn immediately after enqueueing the action and trigger the shortcut in the background

​
Request Body

{
  "url": "https://www.apple.com"
}
With consume_mode: 
{
  "url": "https://www.apple.com",
  "consume_mode": "pop"
}
FieldTypeRequiredDefaultDescription
urlstringYes-URL to open on the phone
consume_modestringNopopHow the shortcut action is consumed. Allowed values: pop, ack

​
Response

Status: 200 OK 
{
  "action_id": "d9083489-5c13-43e8-90ef-52fa9c5a2663",
  "job_id": "aea3fdfb-ec3d-4823-bbac-0b5c64497ebf"
}

​
Behavior

The endpoint:
  1. Validates that the phone belongs to the authenticated organization.
  2. Requires an active subscription.
  3. Requires the phone to be active.
  4. Requires the phone to have an online, selected Mac.
  5. Creates a tracking job with action type open_url.
  6. Enqueues a shortcut action for the phone.
  7. Triggers the Use TapKit shortcut through the Mac and Switch Control.
The enqueued shortcut action looks like this: 
{
  "action_type": "open_url",
  "payload": {
    "url": "https://www.apple.com"
  },
  "consume_mode": "pop",
  "job_id": "<job_id>"
}
The phone shortcut polls for work using: 
POST /v1/shortcut/next-action
X-Shortcut-Token: <phone shortcut token>
The poll response contains the pending action: 
{
  "pending": true,
  "action": {
    "id": "<action_id>",
    "action_type": "open_url",
    "payload": {
      "url": "https://www.apple.com"
    },
    "consume_mode": "pop",
    "job_id": "<job_id>"
  }
}
The shortcut handles action_type == "open_url" by opening payload.url.

​
Consume Modes

ModeBehavior
popThe action is consumed as soon as the shortcut fetches it.
ackThe shortcut must call /v1/shortcut/action-complete after handling the action.

​
Async Mode

Without async=true, the API waits while it attempts to trigger the shortcut, then returns after that trigger attempt. With async=true, the API returns immediately after enqueueing the action and starts the shortcut trigger in the background. 
curl -X POST "https://api.tapkit.ai/v1/phones/{phone_id}/open-url?async=true" \
  -H "X-API-Key: joot_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.apple.com"}'