meCore API

Concepts

A core is a named collection of 1–5 images. When you create one, meCore captions each image and condenses them into a taste profile. The profile is plain text, meant to be fed to a model or matched against a catalogue.

Authentication

Create an API key in your organization dashboard. It is shown once and stored only as a hash — if you lose it, mint a new one.

curl "https://api.mecore.ai/api/v1/org/me" \
  -H "Authorization: Bearer $MECORE_API_KEY"

Creating a core is asynchronous

This is the part worth reading twice. POST /cores does not return a taste profile. It ingests your images, returns 202 with a core id and a job id, and generates the taste in the background — usually 10 to 40 seconds. Poll until it is ready.

# 1. create
curl -X POST "https://api.mecore.ai/api/v1/org/cores" \
  -H "Authorization: Bearer $MECORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Summer looks","imageUrls":["https://cdn.example.com/1.jpg"]}'

# => 202 { "status": 202, "coreId": "c_9f2", "jobId": "job_71a", "coreStatus": "processing" }

# 2. poll
curl "https://api.mecore.ai/api/v1/org/cores/c_9f2" \
  -H "Authorization: Bearer $MECORE_API_KEY"

# => { "status": 200, "coreStatus": "processing", "taste": null }
# => { "status": 200, "coreStatus": "ready", "taste": "A warm, minimal wardrobe…" }

status is always the HTTP status code. The generation state lives in coreStatus on cores and jobStatus on jobs. A coreStatus of "failed" is terminal and carries an error.

Searching products

Once a core is ready, you can match it against our catalogue. This one is synchronous — it runs a model over the catalogue, so expect a few seconds — and it returns the ten best matches in one shot.

curl -X POST "https://api.mecore.ai/api/v1/org/cores/c_9f2/products" \
  -H "Authorization: Bearer $MECORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"winter coats","gender":"female","maxPrice":800}'

# => {
#      "status": 200,
#      "coreName": "Summer looks",
#      "query": "winter coats",
#      "products": [
#        {
#          "id": "p_41c",
#          "title": "Belted wool coat",
#          "designer": "Toteme",
#          "price": 780,
#          "mediaUrl": "https://…/p_41c.jpg",
#          "mediaUrlAlt": null,
#          "url": "https://…"
#        }
#      ]
#    }

• The core must have a coreStatus of "ready". Searching one that is still generating returns 409, not an empty list — poll the core first.
• Exactly one page of results: the 10 best matches, best first. There is no limit parameter, no offset and no total — asking for more is not supported.
• Omit query to search on the taste profile alone, or pass one to narrow it. The catalogue is fashion and apparel only, so a query for anything else returns unrelated clothing rather than nothing.
• Product image URLs are unauthenticated, exactly like core image URLs. Anyone holding one can fetch it.
• url is an affiliate link where the retailer has one, and the retailer's own URL otherwise. Either way it is the link to send a shopper to.

The body is optional — POST with {} to search on the taste profile alone.

Images

• Public https URLs, or base64 data URLs of the form data:image/jpeg;base64,…
• Between 1 and 5 images per core, counted across imageUrls and images together.
• http URLs are rejected. So are private, loopback and link-local addresses.
• The response must have an image/* content type and be under 10MB.

Rate limits

• Requests — 120 per minute. Every REST endpoint, counted per API key — not per IP, so keys never interfere with each other.
• Core creation — 5 per minute. POST /cores and the MCP create_core tool, counted per organization across both. Creating a core ingests up to five images and runs a model, so this cap is deliberately tight.
• Product search — 20 per minute. POST /cores/{id}/products and the MCP search_products tool, counted per organization across both. Each search runs a model over the catalogue.

Over any of these you get a 429 whose message tells you how many seconds to wait. Nothing is charged and no images are fetched on a rejected create — retry after the stated delay.

Deleting a core

• DELETE /cores/{id} removes the core and deletes its images from object storage in the same request. There is no retention window.
• Replacing images with PATCH /cores/{id} deletes the objects behind the images it replaced.
• Both return imagesPurged and imagesFailed. A non-zero imagesFailed means an image could not be removed and may still be reachable at its URL — treat it as an incident, there is no automatic retry.
• Until a core is deleted, its image URLs are unauthenticated: anyone holding one can fetch it. Deletion is what revokes them.
• Every deletion is written to your organization audit log, readable from the dashboard.