API reference · mamitsu

Get started

Quickstart

From a social media post to JSON in three steps.

Sign in with GitHub.
Create a key under API keys.
Send a post with the request in Extract a post.

Get started

Authentication

Send your key as a Bearer token in the Authorization header of every request.

Authorization: Bearer <API key>

New accounts have API access and 100 free credits. Each extraction costs at least 1 credit: 1 per started 30 seconds of video plus 1 per started 3 photos. The full cost is charged when the model is reached, even if extraction fails. Failures before the model are free.

A balance of zero or below returns 402 insufficient_credits before source work starts. An operator-blocked account returns 403 account_not_enabled.

Get started

Connect an AI client

Use mamitsu through MCP, without copying an API key.

Read the MCP integration guide for client setup, tool arguments and production limits.

Add the MCP server URL in a client supporting remote Streamable HTTP and OAuth.
Sign in to mamitsu with GitHub and approve the connection.
Ask your client to extract a post with a URL, prompt and JSON Schema.

The extract tool accepts the same inputs and returns the same data, source and extraction ID as the API. Supported sources, schema rules, limits and credit rates are identical.

Tool results include structured JSON and a JSON text block. Extraction errors useisError: true with the API's public error codes. Authentication and MCP protocol errors are reported by the transport.

Connections use your mamitsu credits. Manage or disconnect them under Connected apps.

In your terminal

claude mcp add --transport http mamitsu https://usemamitsu.com/mcp

On first use, sign in with GitHub and approve the connection.

Extract tool arguments

{
  "url": "https://instagram.com/reel/C8pQ2mLtN4x",
  "prompt": "Extract the recipe.",
  "schema": {
    "type": "object",
    "properties": {
      "dish": { "type": "string" }
    },
    "required": ["dish"]
  }
}

Guides

Extract content from every supported provider.

The API contract stays the same across providers. Choose a guide for a complete request, schema, response, and edge-case example.

TikTok · Send a TikTok URL, a prompt, and a JSON Schema to mamitsu. It watches the video, hears the audio, reads the caption, and returns the information you need as structured JSON.
Instagram Reels · Send an Instagram Reel URL, a prompt, and a JSON Schema to mamitsu. It watches the Reel, hears its audio, reads its caption, and returns the information you need as structured JSON.
YouTube · Send a YouTube video URL, a prompt, and a JSON Schema to mamitsu. It watches the video, hears the audio, reads the available caption, and returns the information you need as structured JSON.
X · Send an X post URL, a prompt, and a JSON Schema to mamitsu. It reads the post text and attached media, then returns the information you need as structured JSON.

API reference

Extract a post

Send a link, a prompt and a JSON Schema. mamitsu watches the video, hears the audio and reads the caption, and returns JSON in the shape of your schema.

POST/api/v1/extract

Request

curl https://usemamitsu.com/api/v1/extract \
  -H "Authorization: Bearer $XTRAKT_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://instagram.com/reel/C8pQ2mLtN4x",
  "prompt": "Extract the recipe.",
  "schema": {
    "type": "object",
    "properties": {
      "dish": { "type": "string" },
      "ingredients": {
        "type": "array",
        "items": { "type": "string" }
      }
    }
  }
}'

Request body

JSON, up to 64 KB. Unknown fields are rejected.

urlString · required

Link to an Instagram post or reel, a YouTube video or Short, a TikTok video, or an X/Twitter post.

Instagram posts, reels and tv: /p/, /reel/, /reels/, /tv/
YouTube: Shorts, watch?v= and youtu.be links, without extra query parameters
TikTok videos: tiktok.com/@user/video/…, vm.tiktok.com/…, vt.tiktok.com/…, tiktok.com/t/… (photo posts are not supported)
X/Twitter: x.com/handle/status/id and twitter.com/handle/status/id. Extract one post's text and attached photos, videos and GIFs, including mixed media. Native photo/video permalinks select the whole post.

Links use HTTPS.

promptString · required

What you're looking for, in your own words. 1 to 10,000 characters.

schemaJSON Schema · required

The shape of the answer. Give each field a description of what it should hold: mamitsu reads it as an instruction. See Writing a schema.

Good to know

Public posts and videos work.
A request times out after 90 seconds.

API reference

Writing a schema

Describe the answer you want in JSON Schema. The root is {"type": "object"}.

Schema

{
  "type": "object",
  "properties": {
    "dish": {
      "type": "string",
      "description": "Name of the dish"
    },
    "ingredients": {
      "type": "array",
      "description": "Every ingredient, one short name each",
      "items": { "type": "string" }
    },
    "cook_minutes": {
      "type": ["integer", "null"],
      "description": "Total cooking time, or null if not stated"
    }
  },
  "required": ["dish", "ingredients", "cook_minutes"],
  "additionalProperties": false
}

Supported keywords

type (string, number, integer, boolean, object, array, null; use ["string", "null"] for optional values)
description, title
properties, required, additionalProperties (true or false)
items, minItems, maxItems
enum, minimum, maximum, format (date, date-time, time), anyOf

Other keywords, such as pattern, minLength, const, allOf and $ref, return invalid_schema naming the keyword. A schema can be up to 16 KB, 8 levels deep and 200 nodes.

Tip

Make a field nullable, like ["string", "null"], for details a post may not mention. You get null for those and clean values for the rest.

When a value is not in the video, you get null if your schema allows it. Otherwise the answer may be a best guess.

API reference

Responses

Success (200)

A 200 response holds your JSON under data, in the shape of your schema and ready for your app. The source of the post comes along with it.

A 200 response always matches your schema. As with any extraction, check the values that matter most to you.

source.provider is instagram, tiktok, youtube or x. source.url is the link you sent.

Response · 200

{
  "extraction_id": "ext_0b6f2c1e-8a1d-4f5e…",
  "data": {
    "dish": "Penne all'arrabbiata",
    "ingredients": [
      "penne", "crushed tomatoes", "garlic",
      "red chili", "olive oil", "parsley"
    ]
  },
  "source": {
    "provider": "instagram",
    "url": "https://instagram.com/reel/C8pQ2mLtN4x"
  }
}

Errors

When a request can't complete, the response carries an error with a code and a message instead of data. The codes are listed below.

Response · 400

{
  "extraction_id": "ext_0b6f2c1e-8a1d-4f5e…",
  "error": {
    "code": "invalid_schema",
    "message": "schema.properties.a: unsupported keyword \"pattern\""
  }
}

API reference

Error codes

Code	HTTP	Meaning
`unauthorized`	401	Missing, wrong or revoked API key.
`insufficient_credits`	402	Valid key, but the credit balance is zero or below.
`account_not_enabled`	403	Valid key, but the account is blocked by an operator.
`invalid_request`	400	Bad JSON, unknown field, or bad prompt. Includes a message.
`invalid_schema`	400	Schema uses something not supported. Includes a message.
`payload_too_large`	413	Request body over 64 KB.
`unsupported_url`	422	Not a supported Instagram, TikTok, YouTube or X URL.
`url_source_inaccessible`	422	Private, removed or blocked post, or it timed out.
`url_source_over_limit`	422	Post too big, or the server is busy. Retry later.
`url_video_too_large`	422	A video is over 50 MB.
`url_video_too_long`	422	Video too long: YouTube over 30 minutes, Instagram/TikTok over 5 minutes, X over 6 minutes in total.
`invalid_extraction`	502	The result could not be made to match your schema.
`extraction_failed`	502	Extraction failed or timed out. Retry.
`server_misconfigured`	500	Server problem. Report it with the extraction_id.

API reference

Tracing

Every response has an extraction_id, also in the x-extraction-id header. Include it when reporting a problem.

mamitsu API reference

Quickstart

Authentication

Connect an AI client

Extract content from every supported provider.

Extract a post

Request body

Good to know

Writing a schema

Supported keywords

Responses

Success (200)

Errors

Error codes

Tracing