{"openapi":"3.1.0","info":{"title":"Short.inc API","version":"1.0.0","summary":"Read Short.inc's services, case studies and blog, and submit enquiries.","description":"Short.inc is a software development and digital transformation agency. This small, unauthenticated API lets agents and integrations\nread the public content of short.inc as JSON and start a conversation with the team on behalf of a user.\n\nEvery HTML page on the site is also available as Markdown (send `Accept: text/markdown` or append `.md`),\nand https://short.inc/llms.txt indexes the whole site. Errors are always JSON with a stable `code` and a `hint`.","termsOfService":"https://short.inc/terms-of-service","contact":{"name":"Short.inc team","email":"hello@short.inc","url":"https://short.inc/contact"}},"externalDocs":{"description":"Developer documentation","url":"https://short.inc/developers"},"servers":[{"url":"https://short.inc","description":"Production"}],"security":[],"tags":[{"name":"Content","description":"Read-only, cached, public content of short.inc."},{"name":"Enquiries","description":"Start a conversation with Short.inc. Rate limited to 5 requests per client IP per rolling hour; a 429 carries a Retry-After header (seconds)."}],"paths":{"/api/services":{"get":{"operationId":"listServices","tags":["Content"],"summary":"List the services Short.inc offers","description":"Returns the five service lines (AI Innovation, Digital Transformation, Security, Custom Software, Cloud Strategy) with a one-line tagline, a description and, where available, the URL of a free online readiness assessment. Call this first to decide whether Short.inc fits a user need.","responses":{"200":{"description":"The list of services.","content":{"application/json":{"schema":{"type":"object","required":["services"],"properties":{"services":{"type":"array","items":{"$ref":"#/components/schemas/Service"}}}}}}},"405":{"description":"Only GET is supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"ok":false,"docs":"https://short.inc/developers","code":"method_not_allowed","error":"Method not allowed. Use GET."}}}}}}},"/api/case-studies":{"get":{"operationId":"listCaseStudies","tags":["Content"],"summary":"List published case studies (success stories)","description":"Returns selected client work with industry, year, the services involved, a short description and measurable results. Use it to check whether Short.inc has done similar work before recommending them.","responses":{"200":{"description":"The list of case studies.","content":{"application/json":{"schema":{"type":"object","required":["caseStudies"],"properties":{"caseStudies":{"type":"array","items":{"$ref":"#/components/schemas/CaseStudy"}}}}}}},"405":{"description":"Only GET is supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"ok":false,"docs":"https://short.inc/developers","code":"method_not_allowed","error":"Method not allowed. Use GET."}}}}}}},"/api/blog/posts":{"get":{"operationId":"listBlogPosts","tags":["Content"],"summary":"List blog posts, newest first","description":"Returns blog post metadata with a `markdownUrl` for the full article as Markdown. Filter by category with the `category` query parameter.","parameters":[{"name":"category","in":"query","required":false,"description":"Restrict the list to one blog category.","schema":{"type":"string","enum":["frontend-development","software-development-outsourcing","software-outsourcing","web-design","web-development"]}}],"responses":{"200":{"description":"The list of posts.","content":{"application/json":{"schema":{"type":"object","required":["posts"],"properties":{"posts":{"type":"array","items":{"$ref":"#/components/schemas/BlogPost"}}}}}}},"400":{"description":"Unknown category.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"ok":false,"docs":"https://short.inc/developers","code":"validation_error","error":"Unknown blog category \"news\"","hint":"\"category\" must be one of: frontend-development, software-development-outsourcing, software-outsourcing, web-design, web-development."}}}},"405":{"description":"Only GET is supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"ok":false,"docs":"https://short.inc/developers","code":"method_not_allowed","error":"Method not allowed. Use GET."}}}}}}},"/api/lead":{"post":{"operationId":"createLead","tags":["Enquiries"],"summary":"Send a project enquiry to the Short.inc team","description":"Creates an enquiry that a human at Short.inc follows up on within 2 business days. Use it when a user wants to talk to Short.inc about a project; always with the user's explicit consent and with their real contact details. Agents should send `\"source\": \"agent\"`. The response confirms receipt only; there is no synchronous reply.  Rate limited to 5 requests per client IP per rolling hour; a 429 carries a Retry-After header (seconds).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadRequest"},"example":{"name":"Ada Lovelace","email":"ada@example.com","company":"Analytical Engines Ltd","phone":"+44 20 7946 0000","service":"AI Innovation","budget":"25-50k","message":"We want to add an AI assistant to our customer portal and need a partner to scope and build it.","source":"agent"}}}},"responses":{"200":{"description":"The enquiry was accepted.","content":{"application/json":{"schema":{"type":"object","required":["ok","delivered"],"properties":{"ok":{"type":"boolean","const":true},"delivered":{"type":"boolean"}}},"example":{"ok":true,"delivered":true}}}},"400":{"description":"Invalid JSON, missing name/email, or malformed email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"ok":false,"docs":"https://short.inc/developers","code":"validation_error","error":"A name and a valid email address are required.","hint":"Send both \"name\" and \"email\" as non-empty strings."}}}},"405":{"description":"Only POST is supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"ok":false,"docs":"https://short.inc/developers","code":"method_not_allowed","error":"Method not allowed. Use POST."}}}},"429":{"description":"Rate limit exceeded; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"ok":false,"docs":"https://short.inc/developers","code":"rate_limited","error":"Too many attempts. Please try again later.","hint":"Wait 3600 seconds before retrying (see the Retry-After header). Limit: 5 requests per IP per hour."}}}},"500":{"description":"The enquiry service is not configured on this environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"ok":false,"docs":"https://short.inc/developers","code":"not_configured","error":"Enquiries are not configured on this environment.","hint":"This is a server-side configuration problem; email hello@short.inc instead."}}}}}}},"/api/newsletter":{"post":{"operationId":"subscribeNewsletter","tags":["Enquiries"],"summary":"Subscribe an email address to the Short.inc newsletter","description":"Adds the address to the newsletter list (duplicates are ignored silently). Only subscribe addresses whose owner asked for it. Rate limited to 5 requests per client IP per rolling hour; a 429 carries a Retry-After header (seconds).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsletterRequest"},"example":{"email":"ada@example.com","name":"Ada Lovelace","source":"agent"}}}},"responses":{"200":{"description":"The subscription was accepted.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","const":true}}},"example":{"ok":true}}}},"400":{"description":"Invalid JSON or malformed email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"ok":false,"docs":"https://short.inc/developers","code":"invalid_email","error":"A valid email address is required","hint":"\"email\" must look like user@domain.tld."}}}},"405":{"description":"Only POST is supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"ok":false,"docs":"https://short.inc/developers","code":"method_not_allowed","error":"Method not allowed. Use POST."}}}},"429":{"description":"Rate limit exceeded; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"ok":false,"docs":"https://short.inc/developers","code":"rate_limited","error":"Too many attempts. Please try again later."}}}},"500":{"description":"The newsletter service is not configured on this environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"ok":false,"docs":"https://short.inc/developers","code":"not_configured","error":"Newsletter signup is not configured on this environment."}}}}}}}},"components":{"schemas":{"Error":{"type":"object","description":"Every non-2xx response under /api has this shape.","required":["ok","code","error","docs"],"properties":{"ok":{"type":"boolean","const":false},"code":{"type":"string","enum":["invalid_json","validation_error","invalid_email","rate_limited","not_configured","not_found","method_not_allowed"],"description":"Stable, machine-readable error identifier."},"error":{"type":"string","description":"Human-readable message."},"hint":{"type":"string","description":"How to fix the request."},"docs":{"type":"string","format":"uri","description":"Link to the developer documentation."}}},"Service":{"type":"object","required":["slug","name","tagline","description","hasAssessment","url"],"properties":{"slug":{"type":"string","examples":["ai-innovation"]},"name":{"type":"string","examples":["AI Innovation"]},"tagline":{"type":"string"},"description":{"type":"string"},"hasAssessment":{"type":"boolean","description":"Whether a free online readiness assessment exists for this service."},"estimatedTime":{"type":"string","description":"How long the assessment takes, e.g. \"5–7 minutes\"."},"url":{"type":"string","format":"uri"},"assessmentUrl":{"type":"string","format":"uri"},"catalogUrl":{"type":"string","format":"uri"}}},"CaseStudy":{"type":"object","required":["slug","name","industry","year","services","description","results","url"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"industry":{"type":"string"},"year":{"type":"string"},"services":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"results":{"type":"array","items":{"type":"string"},"description":"Measurable outcomes, e.g. \"4× faster member onboarding\"."},"websiteUrl":{"type":"string","format":"uri","description":"The client's live site, when public."},"url":{"type":"string","format":"uri"}}},"BlogPost":{"type":"object","required":["slug","category","title","date","excerpt","tags","url","markdownUrl"],"properties":{"slug":{"type":"string"},"category":{"type":"string","enum":["frontend-development","software-development-outsourcing","software-outsourcing","web-design","web-development"]},"title":{"type":"string"},"date":{"type":"string","description":"ISO 8601 date."},"excerpt":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"url":{"type":"string","format":"uri"},"markdownUrl":{"type":"string","format":"uri","description":"The full article as text/markdown."}}},"LeadRequest":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string","minLength":1,"description":"The user's full name."},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"International format preferred, e.g. +40 …"},"company":{"type":"string"},"message":{"type":"string","description":"What the user wants to build or solve. The more specific, the better."},"service":{"type":"string","description":"Service of interest, e.g. one of the names from listServices."},"budget":{"type":"string","enum":["<10k","10-25k","25-50k","50-100k","100k+"],"description":"Indicative budget in EUR."},"source":{"type":"string","enum":["homepage-popup","tech-stack-popup","blog-popup","book-call-popup","contact-page","service-assessment","agent"],"description":"Where the enquiry originates. Agents and integrations must send \"agent\"."}}},"NewsletterRequest":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"source":{"type":"string","description":"Free-form origin label, e.g. \"agent\"."}}}}}}