{
    "openapi": "3.1.0",
    "info": {
        "title": "Agent Links creation API",
        "version": "1.0.0",
        "description": "A focused YOURLS-backed GET and POST link creation API. Independently operated; not an official YOURLS service. Anonymous creation is enabled. Request and archive contents are visible to the operator."
    },
    "servers": [
        {
            "url": "https://yourls.benchmarkhotline.org",
            "description": "Canonical service origin"
        }
    ],
    "externalDocs": {
        "description": "API documentation and collection notice",
        "url": "https://yourls.benchmarkhotline.org/docs/"
    },
    "security": [],
    "paths": {
        "/api/shorten.php": {
            "get": {
                "operationId": "createShortLinkGet",
                "summary": "Create a short link using GET (changes state)",
                "description": "Creates a YOURLS short link and queues its destination for private asynchronous archiving. GET MUTATES STATE. Do not prefetch or crawl this operation. Public URL parameters and accepted request contents are stored verbatim, with IP logging. No creation rate limit. Only public HTTPS HTML/text on port 443 is archived, with a default capture limit of 2 MiB and at most five redirects; scripts and subresources are not fetched. Request logs and archives have configured 30-day retention; YOURLS links and native activity records persist until removed. Read /privacy/ before submitting data.",
                "parameters": [
                    {
                        "name": "url",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uri",
                            "maxLength": 4096,
                            "description": "Absolute HTTP or HTTPS destination, maximum 4096 UTF-8 bytes. Embedded username/password and this service's domains are rejected. Stored verbatim and submitted for private asynchronous archiving.",
                            "example": "https://example.com/guide"
                        }
                    },
                    {
                        "name": "keyword",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "pattern": "^(?!0$)[a-z0-9]{1,64}$",
                            "maxLength": 64,
                            "description": "Optional custom keyword of lowercase ASCII letters and digits. The exact string 0 is reserved.",
                            "example": "exampleguide"
                        }
                    },
                    {
                        "name": "title",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 512,
                            "description": "Optional title; maximum 512 UTF-8 bytes.",
                            "example": "Example guide"
                        }
                    },
                    {
                        "name": "action",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "const": "shorturl",
                            "description": "Optional compatibility parameter. If present, must be shorturl."
                        }
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "const": "json",
                            "description": "Optional compatibility parameter. If present, must be json."
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Created a link or returned the existing destination's short link. Archive status describes queue processing, not successful fetching.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ShortLink"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "413": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "415": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "x-openai-isConsequential": true
            },
            "post": {
                "operationId": "createShortLinkPost",
                "summary": "Create a short link using POST",
                "description": "Creates a YOURLS short link and queues its destination for private asynchronous archiving. GET MUTATES STATE. Do not prefetch or crawl this operation. Public URL parameters and accepted request contents are stored verbatim, with IP logging. No creation rate limit. Only public HTTPS HTML/text on port 443 is archived, with a default capture limit of 2 MiB and at most five redirects; scripts and subresources are not fetched. Request logs and archives have configured 30-day retention; YOURLS links and native activity records persist until removed. Read /privacy/ before submitting data. POST keeps the destination out of the request URL, but public request bodies are still logged. The request body is limited to 16 KiB.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateLink"
                            }
                        },
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateLink"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Created a link or returned the existing destination's short link. Archive status describes queue processing, not successful fetching.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ShortLink"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "413": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "415": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "The request could not be completed. Inspect statusCode and message.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "x-openai-isConsequential": true
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Required only when the deployment disables anonymous creation. Use the Authorization header; never place a token in the query string."
            }
        },
        "schemas": {
            "CreateLink": {
                "type": "object",
                "required": [
                    "url"
                ],
                "properties": {
                    "url": {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 4096,
                        "description": "Absolute HTTP or HTTPS destination, maximum 4096 UTF-8 bytes. Embedded username/password and this service's domains are rejected. Stored verbatim and submitted for private asynchronous archiving.",
                        "example": "https://example.com/guide"
                    },
                    "keyword": {
                        "type": "string",
                        "pattern": "^(?!0$)[a-z0-9]{1,64}$",
                        "maxLength": 64,
                        "description": "Optional custom keyword of lowercase ASCII letters and digits. The exact string 0 is reserved.",
                        "example": "exampleguide"
                    },
                    "title": {
                        "type": "string",
                        "maxLength": 512,
                        "description": "Optional title; maximum 512 UTF-8 bytes.",
                        "example": "Example guide"
                    },
                    "action": {
                        "type": "string",
                        "const": "shorturl",
                        "description": "Optional compatibility parameter. If present, must be shorturl."
                    },
                    "format": {
                        "type": "string",
                        "const": "json",
                        "description": "Optional compatibility parameter. If present, must be json."
                    }
                }
            },
            "ShortLink": {
                "type": "object",
                "required": [
                    "status",
                    "statusCode",
                    "message",
                    "url",
                    "title",
                    "keyword",
                    "shorturl",
                    "archive"
                ],
                "properties": {
                    "status": {
                        "type": "string",
                        "const": "success"
                    },
                    "statusCode": {
                        "type": "integer",
                        "const": 200
                    },
                    "message": {
                        "type": "string",
                        "example": "Short link created."
                    },
                    "url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "title": {
                        "type": "string"
                    },
                    "keyword": {
                        "type": "string"
                    },
                    "shorturl": {
                        "type": "string",
                        "format": "uri"
                    },
                    "archive": {
                        "type": "object",
                        "required": [
                            "status"
                        ],
                        "properties": {
                            "status": {
                                "type": "string",
                                "enum": [
                                    "queued",
                                    "pending",
                                    "processed",
                                    "unavailable"
                                ],
                                "description": "Queue state only. processed means an earlier attempt finished; it does not guarantee successful archival."
                            }
                        }
                    }
                }
            },
            "Error": {
                "type": "object",
                "required": [
                    "status",
                    "statusCode",
                    "message"
                ],
                "properties": {
                    "status": {
                        "type": "string",
                        "const": "fail"
                    },
                    "statusCode": {
                        "type": "integer",
                        "minimum": 400,
                        "maximum": 599
                    },
                    "message": {
                        "type": "string"
                    }
                }
            }
        }
    }
}