REST API Reference

Every route sits under https://example.com/wp-json/infyp/v1/. The namespace string lives in one place, the INFYP_REST_Controller::REST_NAMESPACE constant, and extensions are handed that string rather than hardcoding a copy of it.

Authentication is WordPress core’s, not the plugin’s. Use an Application Password for anything programmatic — create one under Users → Profile → Application Passwords — and cookie authentication with an X-WP-Nonce header for JavaScript running inside wp-admin.

curl -s -u "seo-bot:abcd EFGH ijkl MNOP qrst UVWX" \
  "https://example.com/wp-json/infyp/v1/images?per_page=20&orderby=modified&order=desc"

The plugin issues no tokens of its own and stores no credentials for the API. Both denials carry the code infyp_rest_forbidden: 401 when WordPress did not authenticate the request at all, 403 when it did and the user lacks the capability the route requires.

Capabilities resolve through the action map in INFYP_Security_Manager, which the infyp_capability_map filter can change. Three short action names cover the free routes: optimize and edit_field map to upload_files, manage_settings maps to manage_options.

The two optimize routes are counted against the same api_calls bucket the admin UI uses: 100 calls per hour, per user. Call 101 returns 429 with the error code infyp_rest_rate_limited. Read routes are not counted.

Four routes cover the image resource: two reads and two writes. The writes call the same optimization service the Optimize with AI button uses, so extension field types registered through infyp_allowed_optimize_field_types work here without extra code.

Pagination has two modes. Offset mode is the default and behaves like every other WordPress collection. Cursor mode takes the opaque cursor value from a previous response’s Link header and stays constant-time at any depth, which is what makes it usable on a library of 50,000 images.

Cursor mode carries three constraints. search must be empty, orderby must be date, modified or id, and no X-WP-Total or X-WP-TotalPages header comes back. Sorting by title or seo_score falls back to offset paging without telling you, so pass a supported sort when you rely on cursors.

{
  "id": 482,
  "date": "2026-05-14T09:12:03",
  "modified": "2026-08-02T11:40:55",
  "source_url": "https://example.com/wp-content/uploads/2026/05/harbor-crane-at-dawn.jpg",
  "mime_type": "image/jpeg",
  "filename": "harbor-crane-at-dawn",
  "title": "Harbor crane at dawn",
  "alt_text": "Red container crane above the quay, photographed against a pale sunrise",
  "caption": "",
  "description": "",
  "keywords": [
    "harbor crane",
    "container port",
    "sunrise"
  ],
  "keywords_manual": false,
  "optimized": true,
  "last_optimized": "2026-08-02 11:40:55",
  "seo_score": 86
}

Both write routes take the same body, and the field route adds one parameter of its own. Values are generated in a single AI call, which is why a request can take 10 to 60 seconds; the controller raises the PHP time limit to 120 seconds for the duration. With a Pro license a persisted optimize is three calls — the caption and the description are generated after the base fields are applied — while a dry_run stops before that and stays at one.

A dry run is the safe way to see what a prompt change does to one image before you spend the call budget on a thousand of them.

curl -s -X POST -u "seo-bot:abcd EFGH ijkl MNOP qrst UVWX" \
  -H "Content-Type: application/json" \
  -d '{"custom_prompt":"Product photo. Name the material and the color.","dry_run":true}' \
  "https://example.com/wp-json/infyp/v1/images/482/optimize"

The response splits into what the AI produced and what the image looks like afterwards. On a dry run the second half is unchanged, which makes the two halves easy to diff before you commit to a real run.

{
  "optimization": {
    "new_data": {
      "alt_text": "Red container crane above the quay, photographed against a pale sunrise",
      "title": "Harbor crane at dawn",
      "filename": "harbor-crane-at-dawn",
      "keywords": [
        "harbor crane",
        "container port",
        "sunrise"
      ]
    },
    "model": "gemini-3.1-flash-lite-preview",
    "dry_run": true,
    "prompt_modified": false
  },
  "image": {
    "id": 482,
    "title": "Harbor crane at dawn",
    "seo_score": 86
  }
}

prompt_modified reports whether a callback on the infyp_optimize_prompt filter changed the prompt — Pro page context sets it to true — not whether you sent a custom_prompt yourself.

GET /settings returns what an API client needs before it sends anything: the active model, the output language, the field types the optimize routes accept, and the capabilities any installed extension advertises through infyp_rest_extensions.

{
  "ai_model": "gemini-3.1-flash-lite-preview",
  "connection_method": "api_keys",
  "wp_ai_ready": false,
  "language": "en_US",
  "prompt_addon": "",
  "per_image_prompt": false,
  "allowed_field_types": [
    "filename",
    "alt_text",
    "title"
  ],
  "max_keywords": 3,
  "max_custom_prompt_chars": 1000,
  "request_timeout": 60,
  "extensions": {}
}

PATCH /settings writes the handful of generation settings a client may reasonably switch between requests. Send at least one of them, or the request returns 400 with the code infyp_no_settings.

The scoring configuration — the component weights and the per-field parameters every image is measured against — is readable and writable at /settings/scoring. Four methods, and the difference between two of them is the part worth reading twice.

Both write methods validate the merged result, not the body, so a partial change cannot leave the stored configuration invalid. Weights that do not total exactly 100 are rejected and nothing is written — neither member is saved unless both pass.

curl -s -X PATCH -u "seo-bot:abcd EFGH ijkl MNOP qrst UVWX" \
  -H "Content-Type: application/json" \
  -d '{"weights":{"alt_presence":25,"alt_quality":10}}' \
  "https://example.com/wp-json/infyp/v1/settings/scoring"

The response is the full configuration after the merge, plus one extra member that only appears on writes.

{
  "weights": {
    "alt_presence": 25,
    "alt_quality": 10,
    "title_presence": 15,
    "title_quality": 10,
    "filename_quality": 15,
    "keyword_density": 15,
    "uniqueness": 10
  },
  "parameters": {
    "alt_text": {
      "min_chars": 50,
      "max_chars": 125,
      "tolerance_words": 1,
      "tolerance_chars_pct": 15
    }
  },
  "is_customized": {
    "weights": true,
    "parameters": false
  },
  "scores_stale_since": "2026-08-12 09:31:44",
  "scores_invalidated": 4127
}

Every optimization request that arrives over REST is logged, and the log has its own screen at Image SEO → REST API, directly after API Usage. The page slug is ai-image-seo-optimizer-rest-api and it requires manage_options.

zoom_in

Five counters run across the top of the screen. All of them read from the same log table, so a number that looks wrong is a logging question, not a billing one.

Below the counters, Activity (last 30 days) plots three series — Successful, Failed and Dry runs. Under the chart, the Activity Log table lists Time, User, Route, Image, Mode, Result and Model, filterable by user, route, result and image ID. Mode reads Dry run or Persisted; the per-page screen option defaults to 25 rows.

Extensions register on the shared namespace instead of adding one of their own. The infyp_rest_routes action passes the namespace string and nothing else — no controller instance, no internals — which is exactly how Pro adds /jobs and the context routes.

add_action( 'infyp_rest_routes', function ( $rest_namespace ) {
    register_rest_route(
        $rest_namespace,
        '/images/(?P<id>[\d]+)/publish-check',
        [
            'methods'             => 'GET',
            'permission_callback' => function ( $request ) {
                return current_user_can( 'edit_post', (int) $request['id'] );
            },
            'callback'            => function ( $request ) {
                $image_id = (int) $request['id'];

                return rest_ensure_response( [
                    'image_id' => $image_id,
                    'has_alt'  => '' !== (string) get_post_meta( $image_id, '_wp_attachment_image_alt', true ),
                ] );
            },
        ]
    );
} );

Beyond registering routes, a set of hooks changes what the existing ones do. Every name and signature below is the one shipping in 1.0.6.

Two of these are worth a warning. infyp_rest_optimize_permission runs after the built-in checks, so it can only tighten access, never widen it. infyp_rest_image_response runs on every item of a 100-image collection, so keep it away from per-image queries.

The REST routes are one of three extension surfaces. The PHP helpers do the same work in-process, and WP-CLI drives the same jobs from a shell.