Scan

Macrofy provides powerful, asynchronous image analysis to identify foods and their macros directly from a photo. The scan API handles job creation, GCS image uploads, and delivers the results via a real-time SSE stream.

The scan job model

When you submit an image for analysis, Macrofy creates a recognition job.

Properties

Name
jobId
Type
string
Description
Unique identifier for the scan job.
Name
status
Type
string
Description
The current state of the job (upload_pending, processing, completed, failed).
Name
resultUrl
Type
string
Description
The URL where the full analysis JSON is stored.
Name
result
Type
object
Description
The inline FoodData JSON payload containing macros, calories, and serving size information. This is delivered in the completed event.
Name
created_at
Type
string
Description
Timestamp of when the job was initiated.

POST/v1/scan/image

Create a scan job

Initiate a new image scan job. This endpoint creates a job in the database and returns a pre-signed Google Cloud Storage URL so the client can upload the image bytes directly to the cloud without bottlenecking the API server.

Required attributes

Name
clientId
Type
string
Description
An identifier representing the client app or device.
Name
contentType
Type
string
Description
The MIME type of the image to be uploaded (must be image/jpeg, image/png, or image/webp).

Optional attributes

Name
imageType
Type
string
Description
The source of the image: photo (camera capture) or upload (gallery selection). Defaults to photo.

Request

POST

/v1/scan/image

curl -X POST https://api.macrofy.com/v1/scan/image \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "web-client",
    "contentType": "image/jpeg",
    "imageType": "photo"
  }'

Response

{
  "jobId": "8b2a3d4f-12e3-4c56-b789-0d1c2b3a4f5e",
  "uploadUrl": "https://storage.googleapis.com/macrofy-bucket/client_web-client/uploads/user_xyz/file_8b2a.jpg?X-Goog-Algorithm=..."
}

GET/v1/scan/image/:jobId/stream

Stream scan results

Subscribe to Server-Sent Events (SSE) to receive real-time status updates for a specific scan job. The connection is kept alive with heartbeats every 15 seconds. Once the background worker finishes analyzing the image, a completed event containing the inline JSON result will be emitted, and the connection will automatically close.

Request

GET

/v1/scan/image/8b2a3d4f/stream

curl -N -H "Accept: text/event-stream" \
     -H "Authorization: Bearer {token}" \
     https://api.macrofy.com/v1/scan/image/8b2a3d4f/stream

Stream Output

: heartbeat

data: {"status":"processing","jobId":"8b2a3d4f"}

data: {"status":"completed","jobId":"8b2a3d4f","result":{"name":"Grilled Salmon","calories":350,"protein":40,"carbs":0,"fat":20,"servingSize":150}}