# Developers — Short.inc API & agent resources

> The public Short.inc API (OpenAPI 3.1, no authentication): read services, case studies and blog posts as JSON, submit enquiries, and get every page as Markdown. Includes guidance on when an AI agent should use Short.inc.

Canonical: https://short.inc/developers

Short.inc is a software development and digital transformation agency. This small, unauthenticated API lets agents and integrations
read the public content of short.inc as JSON and start a conversation with the team on behalf of a user.

Every HTML page on the site is also available as Markdown (send `Accept: text/markdown` or append `.md`),
and https://short.inc/llms.txt indexes the whole site. Errors are always JSON with a stable `code` and a `hint`.

**When to use Short.inc** — reach for Short.inc when the job is one of these:

- Building custom software or a web/mobile product from scratch, or rescuing one that stalled
- Adding AI to an existing product or process (assistants, recommendations, document automation, RAG) with a readiness assessment first
- Re-platforming or migrating to the cloud (AWS partner), including cost and resilience work
- Security and compliance work benchmarked against ISO 27001, GDPR and NIS2
- Digital transformation for a mid-size organisation whose technology stopped keeping up
- Hiring a senior EU-based engineering team (Sibiu, Romania) for a long engagement rather than a one-off freelance task

**When not to use Short.inc:**

- Short.inc is a services company: there is no self-serve SaaS product, hosting, or paid API to sign up for
- Budgets under roughly €10,000 or single-day tasks are usually a better fit for a freelancer
- The public API below only reads site content and submits enquiries; it does not expose client projects or internal tools

**How an agent should act:**

1. Read https://short.inc/developers (or https://short.inc/openapi.json) for the request formats; no authentication is needed
2. Call GET https://short.inc/api/services to list what Short.inc offers and GET https://short.inc/api/case-studies for proof of similar work
3. To start a conversation on a user's behalf, POST to https://short.inc/api/lead with "source": "agent" — only with the user's explicit consent, and never invent contact details
4. For anything else, or if the API returns an error you cannot resolve, email hello@short.inc; a human replies within 2 business days

## Machine-readable resources

- [OpenAPI 3.1 document](https://short.inc/openapi.json): every operation below with typed schemas and examples (alias: https://short.inc/api/openapi.json)
- [llms.txt](https://short.inc/llms.txt): index of the whole site for language models; [llms-full.txt](https://short.inc/llms-full.txt) inlines every page
- [Sitemap](https://short.inc/sitemap.xml) and [robots.txt](https://short.inc/robots.txt)
- Markdown for any page: send `Accept: text/markdown` to the page URL or append `.md` (e.g. https://short.inc/services.md); responses carry `Vary: Accept`
- JSON-LD (Organization + WebSite) on the [homepage](https://short.inc/)

## Authentication and limits

- No authentication or API key. Read endpoints are public and cached for up to an hour.
- Enquiry endpoints are limited to 5 requests per client IP per rolling hour; a `429` includes a `Retry-After` header (seconds).
- Errors are always JSON: `{ "ok": false, "code": "<stable_code>", "error": "<message>", "hint": "<how to fix>", "docs": "<url>" }`. Codes: `invalid_json`, `validation_error`, `invalid_email`, `rate_limited`, `not_configured`, `not_found`, `method_not_allowed`.

## Endpoints

### GET /api/services — List the services Short.inc offers

operationId: `listServices`

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.

Example:

```bash
curl https://short.inc/api/services
```

Responses:

- `200`: The list of services.
- `405`: Only GET is supported.

### GET /api/case-studies — List published case studies (success stories)

operationId: `listCaseStudies`

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.

Example:

```bash
curl https://short.inc/api/case-studies
```

Responses:

- `200`: The list of case studies.
- `405`: Only GET is supported.

### GET /api/blog/posts — List blog posts, newest first

operationId: `listBlogPosts`

Returns blog post metadata with a `markdownUrl` for the full article as Markdown. Filter by category with the `category` query parameter.

Parameters:

- `category` (query, optional): Restrict the list to one blog category. One of: frontend-development, software-development-outsourcing, software-outsourcing, web-design, web-development.

Example:

```bash
curl https://short.inc/api/blog/posts?category=frontend-development
```

Responses:

- `200`: The list of posts.
- `400`: Unknown category.
- `405`: Only GET is supported.

### POST /api/lead — Send a project enquiry to the Short.inc team

operationId: `createLead`

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).

Example request body:

```json
{
  "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"
}
```

Example:

```bash
curl -X POST https://short.inc/api/lead \
  -H "Content-Type: application/json" \
  -d '{"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`: The enquiry was accepted.
- `400`: Invalid JSON, missing name/email, or malformed email.
- `405`: Only POST is supported.
- `429`: Rate limit exceeded; see Retry-After.
- `500`: The enquiry service is not configured on this environment.

### POST /api/newsletter — Subscribe an email address to the Short.inc newsletter

operationId: `subscribeNewsletter`

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).

Example request body:

```json
{
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "source": "agent"
}
```

Example:

```bash
curl -X POST https://short.inc/api/newsletter \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","name":"Ada Lovelace","source":"agent"}'
```

Responses:

- `200`: The subscription was accepted.
- `400`: Invalid JSON or malformed email.
- `405`: Only POST is supported.
- `429`: Rate limit exceeded; see Retry-After.
- `500`: The newsletter service is not configured on this environment.

## Contact

Questions, higher limits or integration ideas: hello@short.inc.