{
    "documentation_version": 1,
    "base_url": "https://c7dev.com",
    "instructions_url": "https://c7dev.com/api_instructions",
    "selection": {
        "method": "GET",
        "parameter": "api",
        "required": false,
        "description": "Omit api for the full suite, or use an endpoint name for its instructions only.",
        "example_url": "https://c7dev.com/api_instructions?api=media_api"
    },
    "instructions": [
        "Choose an endpoint by its description, then use its documented HTTP method and parameter location.",
        "URL-encode GET query values. Preserve identifiers such as VAT numbers and registration codes as strings.",
        "For JSON APIs, require HTTP success and result=true before using returned data. Read error_message on failure.",
        "Do not fabricate missing data or treat null as zero or false. Warnings may indicate incomplete or older data.",
        "Do not blindly retry invalid input or access errors. Temporary service failures may be retried with bounded backoff.",
        "Responses prohibit browser caching. Inspect cached, timestamps and X-API-Version when those fields are available."
    ],
    "authentication": {
        "documentation": "Public; no token is required to read these instructions.",
        "restricted_endpoints": "Supply credentials provided by the API operator when access control requires them.",
        "token_locations": [
            "Authorization: Bearer YOUR_ACCESS_TOKEN",
            "X-Access-Token: YOUR_ACCESS_TOKEN",
            "access_token query or form parameter"
        ],
        "domain": "Send domain as a query or form parameter when the client token is restricted to registered domains. Access may also be restricted by IP.",
        "ai_generate": "Requires both access_token and domain in the form body."
    },
    "json_response_envelope": {
        "result": "boolean; request succeeded",
        "error": "boolean; request failed",
        "error_message": "string; empty on success",
        "server_time": "integer; Unix timestamp in seconds"
    },
    "errors": {
        "400": "Missing or invalid input.",
        "403": "Access denied; check token, registered domain and IP permissions.",
        "404": "Unknown API selected for instructions.",
        "405": "Unsupported method for the instructions endpoint.",
        "500": "Processing failed.",
        "503": "Service temporarily unavailable."
    },
    "apis": [
        {
            "name": "stockimages_api",
            "method": "GET",
            "path": "/stockimages_api",
            "description": "Search stock images by keywords or phrases and return image URLs, descriptions and dimensions.",
            "instructions_url": "https://c7dev.com/api_instructions?api=stockimages_api",
            "request": {
                "parameter_location": "query",
                "parameters": {
                    "search": {
                        "type": "string",
                        "required": true,
                        "description": "Keywords or phrases to search for images. Preserved in query; sources may add dimension filters.",
                        "maxLength": 500
                    },
                    "min_width": {
                        "type": "integer",
                        "required": false,
                        "description": "Minimum delivered image width in pixels, inclusive.",
                        "minimum": 1
                    },
                    "min_height": {
                        "type": "integer",
                        "required": false,
                        "description": "Minimum delivered image height in pixels, inclusive.",
                        "minimum": 1
                    },
                    "limit": {
                        "type": "integer",
                        "required": false,
                        "description": "Number of qualifying images to return when available.",
                        "default": 5,
                        "minimum": 1,
                        "maximum": 50
                    }
                }
            },
            "response": {
                "format": "application/json",
                "response_fields": [
                    "items",
                    "query",
                    "count",
                    "fetched_at",
                    "cached",
                    "warnings"
                ],
                "item_fields": [
                    "id",
                    "provider",
                    "title",
                    "description",
                    "keywords",
                    "image_url",
                    "thumbnail_url",
                    "preview_url",
                    "width",
                    "height",
                    "aspect_ratio",
                    "orientation",
                    "resolution",
                    "megapixels",
                    "is_square",
                    "is_landscape",
                    "is_portrait",
                    "rank",
                    "query",
                    "fetched_at",
                    "cached",
                    "source_url"
                ],
                "headers": {
                    "X-API-Version": "stockimages_api_v7"
                }
            },
            "details": {
                "Search": "Required search text; optional min_width and min_height set minimum delivered image dimensions in pixels",
                "Limit": "Optional limit from 1 to 50; defaults to 5 images",
                "Returns": "Up to limit qualifying images; additional sources are queried only to fill missing results",
                "Ranking": "Closest keyword matches and focused titles first; source quality markers and delivered resolution break relevance ties"
            },
            "notes": [
                "Use GET with required search and optional min_width, min_height and limit. URL-encode the search text. limit defaults to 5 and must be an integer from 1 to 50.",
                "Returns up to limit qualifying images. Sources are checked in order; later sources are queried only while the requested number of distinct accepted images has not been collected. count is the number returned, not the total available upstream.",
                "Minimum dimensions apply to the delivered image_url, not thumbnails. For resized source images, C7 derives the delivered dimensions from the original aspect ratio and size cap. When both minima are set, both must be met. Images with an unknown required dimension are excluded. C7 always filters results and also sends dimension filters to sources that support them.",
                "The requested result target applies with or without dimension filters. Invalid, undersized and duplicate images do not count toward it. The primary source is preferred and the final fallback is queried only when the target remains unfilled.",
                "C7 ranks the complete candidate pages before selecting limit images. Exact titles and phrases, more matching search words and fewer unrelated title words rank higher; genuine source keywords and descriptions provide weaker matches. Generated fallback text does not improve relevance.",
                "For equivalent keyword relevance, source quality or featured-image markers and higher delivered resolution rank higher. Remaining ties preserve source relevance order. rank reflects the final combined order, including any fallback images.",
                "If every configured source has been checked and fewer images qualify than requested, the available images are returned. The first relevance page of each needed source is checked with a size adjusted to limit where supported; later pages are not fetched. Each combination of search, minimum dimensions and limit has its own cache.",
                "Every item includes all documented fields. An image URL and a stable source identifier are required for acceptance.",
                "Missing thumbnails and previews fall back to image_url. Missing dimensions and their derived values are null; image files are not downloaded to inspect dimensions.",
                "rank starts at 1. Orientation is landscape, portrait or square. resolution uses WIDTHxHEIGHT; megapixels and aspect_ratio are numeric.",
                "query preserves the original search text. fetched_at is a UTC retrieval timestamp and remains unchanged on cache hits. cached reflects whether C7 reused cached data.",
                "Searches that fill the requested limit cache for up to one hour, searches with fewer images for five minutes, and results with source failures for one minute. Some sources require a separate 24-hour request cache; result caches never extend expiring image URLs beyond their source lifetime. Warnings indicate a temporarily unavailable source; other sources can still return images.",
                "source_url links to the original resource page when available."
            ],
            "examples": [
                {
                    "method": "GET",
                    "url": "https://c7dev.com/stockimages_api?search=forest%20sunrise"
                },
                {
                    "method": "GET",
                    "url": "https://c7dev.com/stockimages_api?search=modern%20office%20interior&min_width=1920&min_height=1080&limit=20"
                }
            ]
        }
    ],
    "result": true,
    "error": false,
    "error_message": "",
    "server_time": 1791748769
}