TAP Image Tagging API

Overview

TAP image tagging is suggestions-only. The AI service receives caller-provided post context, media, and optional existing tags, then returns recommended tags and optional captions. It does not call TAP dashboard/public APIs and does not update TAP posts.

note

All requests require the normal APIM authentication headers: Authorization: Bearer {access_token} and Ocp-Apim-Subscription-Key: {subscription_key}.

Endpoints

The paths below include the TAP APIM /ai prefix. Direct Mastra app smoke tests use the same paths without /ai.

Method	Endpoint	Description
POST	/ai/tap/tools/tagging-suggestions	Preferred TAP-facing tool endpoint for synchronous image/media tagging and caption suggestions
POST	/ai/tap/workflows/tagging-suggestions	Backwards-compatible synchronous endpoint from the previous integration

Both endpoints run the same tagging service. The tool endpoint returns the standard { data } tool envelope. The backwards-compatible workflow endpoint returns the tagging result directly, matching the previous integration shape.

Request

{
  "options": {
    "maxTagsPerPost": 6,
    "generateCaption": true,
    "includeReasoning": true
  },
  "posts": [
    {
      "postId": 12345,
      "tenantId": "tap",
      "university": {
        "id": "uol",
        "name": "University of Liverpool"
      },
      "text": "Graduation day on campus",
      "caption": null,
      "media": [
        {
          "url": "https://example.test/signed-image.jpg",
          "type": "image",
          "altText": null
        }
      ],
      "existingTags": [],
      "userContext": {
        "country": "Thailand"
      }
    }
  ]
}

Example synchronous request:

curl -X POST "{tap_apim_base_url}/ai/tap/tools/tagging-suggestions" \
  -H "Authorization: Bearer {access_token}" \
  -H "Ocp-Apim-Subscription-Key: {subscription_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "maxTagsPerPost": 6,
      "generateCaption": true,
      "includeReasoning": true
    },
    "posts": [
      {
        "postId": 12345,
        "tenantId": "tap",
        "text": "Graduation day on campus",
        "media": [
          {
            "url": "https://example.test/signed-image.jpg",
            "type": "image"
          }
        ],
        "existingTags": []
      }
    ]
  }'

Existing callers using the previous workflow endpoint can continue sending the same body to:

curl -X POST "{tap_apim_base_url}/ai/tap/workflows/tagging-suggestions" \
  -H "Authorization: Bearer {access_token}" \
  -H "Ocp-Apim-Subscription-Key: {subscription_key}" \
  -H "Content-Type: application/json" \
  -d '{ "...": "same request body as above" }'

Request Fields

Field	Type	Required	Description
options.maxTagsPerPost	integer	No	Maximum number of suggested tags per post.
options.generateCaption	boolean	No	Whether the response should include a suggested caption.
options.includeReasoning	boolean	No	Whether the response should include concise reasoning.
posts	array	Yes	Posts to process.
posts[].postId	string or number	Yes	Caller-provided post identifier returned in the result.
posts[].tenantId	string	No	Caller-provided tenant or TAP partition identifier.
posts[].university	object	No	Optional university context used by the model.
posts[].text	string	No	Post text or context.
posts[].caption	string or null	No	Existing caption, when present.
posts[].media	array	Yes	Image or video-thumbnail media to inspect. Posts without supported media are skipped.
posts[].existingTags	array	No	Tags already attached to the post.
posts[].userContext	object	No	Optional caller context such as country, audience, or campaign metadata.

Response

The tool endpoint returns the result inside data:

{
  "data": {
    "jobId": "7f4b9a2e-2f0a-4e0a-8d8c-9b6f6f8f2a31",
    "processed": 1,
    "results": [
      {
        "postId": 12345,
        "status": "success",
        "caption": "Students celebrate graduation on campus.",
        "tags": ["Graduation", "Campus", "Students"],
        "confidence": "high",
        "reasoning": "The image and post text indicate a graduation scene."
      }
    ],
    "errors": []
  }
}

The backwards-compatible workflow endpoint returns the same result without the data envelope:

{
  "jobId": "7f4b9a2e-2f0a-4e0a-8d8c-9b6f6f8f2a31",
  "processed": 1,
  "results": [
    {
      "postId": 12345,
      "status": "success",
      "caption": "Students celebrate graduation on campus.",
      "tags": ["Graduation", "Campus", "Students"],
      "confidence": "high",
      "reasoning": "The image and post text indicate a graduation scene."
    }
  ],
  "errors": []
}

Notes

• Use signed media URLs that remain accessible for the duration of processing.
• The AI service only returns suggestions. TAP decides whether to apply tags or captions.
• TAP platform write credentials are not required for this path.