Open URL

curl --request POST \
  --url https://api.example.com/v1/phones/{phone_id}/open-url

import requests

url = "https://api.example.com/v1/phones/{phone_id}/open-url"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.example.com/v1/phones/{phone_id}/open-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/phones/{phone_id}/open-url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/phones/{phone_id}/open-url"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/phones/{phone_id}/open-url")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/phones/{phone_id}/open-url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

phones

{phone_id}

open-url

Open URL

curl --request POST \
  --url https://api.example.com/v1/phones/{phone_id}/open-url

import requests

url = "https://api.example.com/v1/phones/{phone_id}/open-url"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.example.com/v1/phones/{phone_id}/open-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/phones/{phone_id}/open-url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/phones/{phone_id}/open-url"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/phones/{phone_id}/open-url")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/phones/{phone_id}/open-url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

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

Parameter	Type	Description
`phone_id`	`string`	The phone identifier

Query Parameters

Parameter	Type	Default	Description
`async`	`boolean`	`false`	Return 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"
}

Field	Type	Required	Default	Description
`url`	`string`	Yes	-	URL to open on the phone
`consume_mode`	`string`	No	`pop`	How 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:

Validates that the phone belongs to the authenticated organization.
Requires an active subscription.
Requires the phone to be active.
Requires the phone to have an online, selected Mac.
Creates a tracking job with action type open_url.
Enqueues a shortcut action for the phone.
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

Mode	Behavior
`pop`	The action is consumed as soon as the shortcut fetches it.
`ack`	The 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"}'

Open App Run Shortcut

Getting Started

Features

Endpoints

Open URL

Request

Path Parameters

Query Parameters

Request Body

Response

Behavior

Consume Modes

Async Mode

​Request

​Path Parameters

​Query Parameters

​Request Body

​Response

​Behavior

​Consume Modes

​Async Mode

​Related

Request

Path Parameters

Query Parameters

Request Body

Response

Behavior

Consume Modes

Async Mode

Related