Skip to main content
GET
/
v1
/
phones
/
{phone_id}
/
screenshot
Screenshot
curl --request GET \
  --url https://api.example.com/v1/phones/{phone_id}/screenshot

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.

Capture a screenshot from the phone’s current screen. This is an inspection endpoint: the Mac app reads the current phone screen and returns image data. It does not send input to the phone or change phone state.

​
Request

curl https://api.tapkit.ai/v1/phones/{phone_id}/screenshot \
  -H "X-API-Key: joot_your_api_key" \
  --output screenshot.png

​
Path Parameters

ParameterTypeDescription
phone_idstringThe phone identifier

​
Query Parameters

ParameterTypeDefaultDescription
asyncbooleanfalseReturn immediately with job ID

​
Synchronous Response

Returns PNG image data directly with Content-Type: image/png.

​
Asynchronous Response

When ?async=true: 
{
  "job_id": "job_abc123"
}
Retrieve the screenshot via GET /jobs/{job_id}/download.

​
Examples

​
Sync Screenshot (curl)

curl https://api.tapkit.ai/v1/phones/abc123/screenshot \
  -H "X-API-Key: joot_..." \
  --output screen.png

​
Sync Screenshot (Python)

import requests

response = requests.get(
    f"https://api.tapkit.ai/v1/phones/{phone_id}/screenshot",
    headers={"X-API-Key": "joot_..."}
)

with open("screenshot.png", "wb") as f:
    f.write(response.content)

​
Async Screenshot

# Request screenshot asynchronously
response = requests.get(
    f"https://api.tapkit.ai/v1/phones/{phone_id}/screenshot?async=true",
    headers={"X-API-Key": "joot_..."}
)
job_id = response.json()["job_id"]

# Poll for completion
while True:
    job = requests.get(
        f"https://api.tapkit.ai/v1/jobs/{job_id}",
        headers={"X-API-Key": "joot_..."}
    ).json()

    if job["status"] == "completed":
        break
    time.sleep(0.1)

# Download the image
image = requests.get(
    f"https://api.tapkit.ai/v1/jobs/{job_id}/download",
    headers={"X-API-Key": "joot_..."}
)

with open("screenshot.png", "wb") as f:
    f.write(image.content)

​
Errors

​
Mac App Not Running

{
  "error": "MAC_APP_NOT_RUNNING",
  "message": "Mac companion app is not connected"
}

​
Timeout

{
  "error": "TIMEOUT",
  "message": "Screenshot capture timed out"
}
HTTP Status: 408 Request Timeout