Skip to content

Commit adf47f0

Browse files
francescobiancofrancescobianco
committed
docs(knowledge): organize knowledge base in English with OAS specs, service references, platform guide and FAQ
1 parent a01915c commit adf47f0

66 files changed

Lines changed: 1491 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.convcommit‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# convcommit - Conventional Commit message builder
2+
# This file is read by the `convcommit` CLI tool to populate
3+
# the interactive selector menus.
4+
# Commit this file to share the project's commit vocabulary with the team.
5+
#
6+
# FORMAT
7+
# type:<value> — commit type option (e.g. fix, feat, docs)
8+
# scope:<value> — commit scope option
9+
# message:<value> — commit message template
10+
#
11+
# SPECIAL PREFIXES
12+
# ~<value> — marks the default selection
13+
# _ — enables free-text manual input (press ".")
14+
# [X]<value> — forces key letter X for this entry (e.g. [B]build, [W]wip)
15+
#
16+
# HOW TO USE (interactive)
17+
# Run `convcommit` in a git repo. A menu appears for type, scope, message.
18+
# Press the letter in brackets [A][B]... or [.] for free-text input.
19+
# Stage and push in one shot:
20+
# convcommit -a -p
21+
#
22+
# HOW TO USE (direct flags — scripts, AI agents)
23+
# Bypass the selector entirely with explicit flags:
24+
# convcommit --type fix --scope auth --message "fix null pointer" --push
25+
# convcommit -t feat -s api -m "add endpoint" -a -p
26+
#
27+
# SMART PATTERN — stage specific files and commit in one command
28+
# Use --add instead of nested command substitution.
29+
# Anti-pattern (avoid):
30+
# msg=$(convcommit --type fix --message "fix") && git commit -m "$msg" && git push
31+
# Recommended:
32+
# convcommit --add src/auth.sh --type fix --scope auth --message "fix null pointer" --push
33+
# Stage multiple files:
34+
# convcommit --add src/auth.sh --add tests/auth_test.sh -t test -s auth -m "add tests" -p
35+
#
36+
# HOW TO USE (pipe / non-interactive)
37+
# Pipe selections as lines: one per stage (type, scope, message).
38+
# Use the letter shown in the menu, or "." to trigger free-text input.
39+
# Examples:
40+
# printf "G\n.\nfix null pointer in login\n" | convcommit
41+
# printf "F\n\nadd endpoint\n" | convcommit -a -p
42+
# Capture just the formatted message:
43+
# msg=$(printf "G\n\nfix null pointer\n" | convcommit)
44+
#
45+
# OTHER USEFUL FLAGS
46+
# --reset Regenerate this file with the latest defaults
47+
# --help Show all options
48+
#
49+
# INSTALLATION
50+
# convcommit is a single bash file with no dependencies.
51+
# Install it locally in your project:
52+
# curl -fsSL https://raw.githubusercontent.com/francescobianco/convcommit/refs/heads/main/bin/convcommit \
53+
# -o bin/convcommit && chmod +x bin/convcommit
54+
# Or system-wide:
55+
# curl -fsSL https://raw.githubusercontent.com/francescobianco/convcommit/refs/heads/main/bin/convcommit \
56+
# -o /usr/local/bin/convcommit && chmod +x /usr/local/bin/convcommit
57+
type:[B]build
58+
type:~chore
59+
type:[D]docs
60+
type:deps
61+
type:feat
62+
type:fix
63+
type:ci
64+
type:init
65+
type:merge
66+
type:perf
67+
type:refactor
68+
type:revert
69+
type:security
70+
type:style
71+
type:test
72+
type:[W]wip
73+
scope:_
74+
scope:~
75+
message:_
76+
message:~_

‎knowledge/README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Knowledge base
2+
3+
Everything needed to build and maintain the agent skills for interacting with the [Openapi](https://openapi.com) API marketplace.
4+
5+
## Contents
6+
7+
| File / folder | What it contains |
8+
|---|---|
9+
| [company-profile.md](company-profile.md) | Who Openapi is: company facts, history, offering, certifications, data sources |
10+
| [services-catalog.md](services-catalog.md) | Catalog of all 28 APIs with base URLs, categories, and deprecation status |
11+
| [platform-guide.md](platform-guide.md) | Cross-cutting platform knowledge: OAuth v2 authentication, scopes, billing, sandbox, async patterns |
12+
| [faq.md](faq.md) | Console FAQ (account, API usage, payments and subscriptions) |
13+
| [references.md](references.md) | External references: websites, GitHub repos (SDKs, CLI, MCP server), Postman, status page |
14+
| [services/](services/) | Per-service endpoint references (generated from the OAS specs) |
15+
| [oas/](oas/) | Snapshot of the official OpenAPI 3 specs from [openapi/openapi-cli](https://github.com/openapi/openapi-cli/tree/main/oas) |
16+
17+
## Keeping it up to date
18+
19+
- Canonical spec URLs: `https://console.openapi.com/oas/en/<service>.openapi.json` (full list in [oas/00-list.txt](oas/00-list.txt)). Re-download into `oas/` and regenerate `services/` when specs change.
20+
- The API Library at https://console.openapi.com/apis is the source of truth for which APIs are active or deprecated.

‎knowledge/company-profile.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Who is Openapi?
2+
3+
> Sources: https://openapi.com/ · https://openapi.com/about-us · https://console.openapi.com/support (structured data) · GitHub organization profile
4+
5+
Openapi® (Openapi S.p.A.) is **the largest certified API marketplace in Europe**, based in Rome, Italy. It empowers businesses to accelerate digital transformation, simplify operations, and innovate faster through APIs. Slogan: **"API Made Simple"**.
6+
7+
## Company facts
8+
9+
| Fact | Value |
10+
|---|---|
11+
| Legal name | Openapi SpA |
12+
| VAT / Tax ID | IT 12485671007 |
13+
| Founded | 2013-10-20, Rome |
14+
| Founder | Luca Scuriatti |
15+
| Key people | Simone Desantis (CTO), Shaun De Lucia (COO), Alessandro Mollicone (CMO) |
16+
| Headquarters | Viale Filippo Tommaso Marinetti 221, 00154 Rome, Italy |
17+
| Parent | Open Holding Srl |
18+
| Memberships | Linux Foundation, Assintel, ANCIC, Organismo di Monitoraggio |
19+
| Awards | FT1000 (Financial Times, 2023), Leader della Crescita (Il Sole 24 Ore, 2024) |
20+
21+
## History
22+
23+
- **2013** — Founded; first operational office in Rome.
24+
- **2016** — Research & Development center opened in Terni.
25+
- **2018** — Started third-party API development.
26+
- **2021** — Launch of the Openapi.com marketplace.
27+
- **2023** — Incorporated as a joint-stock company (SpA).
28+
29+
## What Openapi offers
30+
31+
A single platform exposing **400+ API services** about companies, individuals, real estate, automotive, finance, direct marketing, digital trust, and communication, organized in 10 main categories: AI, Automotive, Business Information, Digital Transformation, Communication, ID & Trust, Official Documents, Person, Real Estate, Other APIs.
32+
33+
Key numbers (2024): 100M+ API requests per year, 14,000+ users, 12,000+ customers (including Crédit Agricole, PwC, Deliveroo).
34+
35+
Key advantages:
36+
37+
- 400+ API services on one platform
38+
- Certified, up-to-date data sources
39+
- Simple integration, pay-as-you-go pricing (wallet) or subscriptions
40+
- Secure and scalable infrastructure
41+
- "Codeless" integrations via MCP and CRM connectors (HubSpot, Odoo, Salesforce)
42+
43+
Target industries: Banking & Financial, Credit Recovery, E-commerce, Insurance, Real Estate, Retail, Sales, Software & IT, Startups, Telecommunications.
44+
45+
## Certifications
46+
47+
- UNI EN ISO 9001:2015 — Quality Management
48+
- ISO/IEC 27001:2022 — Information Security Management
49+
- ISO 25012:2014 — Data Quality
50+
- UNI PdR 125:2022 — Gender Equality
51+
52+
## Data sources
53+
54+
All data comes from official and certified sources, including:
55+
56+
- **Revenue Agency (Agenzia delle Entrate)** — real estate/land registry data, invoicing codes, company activity status
57+
- **Chamber of Commerce Company Register** — company registration reports (visure), financial statements, XBRL
58+
- **CRIF** — personal, economic, employee, web and exponent data of Italian companies
59+
- **INPS** — quarterly employee headcount data
60+
- **Poste Italiane** — registered mail, telegrams, court documents (single or bulk)
61+
- **Ministry of Transport** (European basis) — vehicle information and services
62+
- **European Certification Authorities and Identity Providers** — digital signature, SPID, time stamping, certified e-mail (PEC/REM)
63+
- **National Research Council (CNR)** — certified registrar for website/domain information
64+
- **IndicePA** — index of Italian public administrations
65+
- **Protest Register and other registers** — negative events and score calculation
66+
- Tax Assistance Centres (CAF), company social accounts and websites, proprietary forecasting systems

‎knowledge/faq.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Openapi Console FAQ
2+
3+
> Source: https://console.openapi.com/support (extracted 2026-06-10)
4+
5+
## Account
6+
7+
**How can I sign up on Openapi?**
8+
You can sign up via: (1) Google account, (2) GitHub account, (3) email address. With email you receive instructions within a few seconds to complete the registration.
9+
10+
**I did not receive the email after registering, what should I do?**
11+
The email is only sent when email was chosen as registration method. Check the Promotions/Updates tab (Gmail) and the spam folder; otherwise contact the [Support Form](https://openapi.it/en/support).
12+
13+
**Can I change my password?**
14+
Yes, if you registered by email: in your personal area, section Preferences.
15+
16+
**I have forgotten my password, what can I do?**
17+
- Email registration: click "I forgot my password" in the login area.
18+
- Google account: follow Google's account-recovery procedure.
19+
- GitHub account: use GitHub's "Forgot password?".
20+
21+
**Is it possible to add an additional user to my Openapi account?**
22+
No — one email per account. An additional email can be added for notifications only.
23+
24+
**Can I delete my Openapi account?**
25+
Yes, in Preferences → "Delete your account". WARNING: data is permanently deleted and tokens are invalidated; this cannot be undone.
26+
27+
## API usage
28+
29+
**What are the differences between individual and subscription requests?**
30+
Requests are paid from the wallet ("purse", per request) or via subscription. Subscriptions have a monthly/yearly request limit but a lower cost per request; single requests are unlimited as long as you have credit.
31+
32+
**Is it possible to access free requests?**
33+
Yes, some APIs include daily and/or monthly free requests, shown in the API's Price section.
34+
35+
**How does the Sandbox area work?**
36+
The sandbox is for testing before production. Test requests are free, but you must set up "sandbox credit" first. Sandbox responses are illustrative and may be incomplete; some APIs provide test VAT numbers.
37+
38+
**How do I create the token?**
39+
Two ways: via the OAuth API (POST to the token endpoint) or via the "New Token" tool in the console's Authentication section.
40+
41+
**Where can I view my tokens?**
42+
In your private area under Authentication, where you can also create new tokens (+New Token).
43+
44+
**Can I check my consumption?**
45+
Yes — per single call, per subscription, and per API in the dedicated tab.
46+
47+
**How can I check rate limits on endpoints?**
48+
Any limits are indicated in the descriptions of the individual APIs.
49+
50+
**From which sources does the data provided by Openapi come?**
51+
Only official and certified sources — see [company-profile.md](company-profile.md#data-sources) for the full list (Revenue Agency, Chamber of Commerce, CRIF, INPS, Poste Italiane, Ministry of Transport, CNR, IndicePA, Protest Register, certification authorities, CAF, company websites/socials, proprietary processing).
52+
53+
**Why is the identity document submission procedure necessary to activate certain APIs?**
54+
Some services fall under the Italian TULPS regulation (Article 6 license), which requires identification of the requesting individual or company.
55+
56+
**Which document should I upload for identity verification?**
57+
A driver's license, passport, or identity card of the legal representative, of a person with signing powers, or of a delegate (e.g., IT manager or administrative office).
58+
59+
**Can I contact you for assistance?**
60+
Yes, via the [Support Form](https://openapi.it/en/support).
61+
62+
## Payments and subscriptions
63+
64+
**I would like to top up my credit, how do I do this?**
65+
Personal area → Transactions → "Recharge your wallet". You can also enable Auto Recharge (automatic top-up below a threshold; credit card only).
66+
67+
**What are the payment methods?**
68+
PayPal, credit card, bank transfer. Credit card requires recurring payment for monthly/annual subscriptions (deactivatable anytime). Auto-recharge is available for credit card only.
69+
70+
**How does Auto-Recharge work?**
71+
Set a minimum threshold and a top-up amount at purchase time; the top-up triggers only when credit falls below the threshold. Deactivatable anytime; credit card only.
72+
73+
**I would like to activate a subscription, how can I do?**
74+
Select the desired plan in the dedicated section at the API level.
75+
76+
**How do monthly and annual subscriptions work?**
77+
Monthly: 30 days, unused requests do not roll over. Annual: 365 days; requests (net of API-specific instalment limits) can be used at any pace over the year.
78+
79+
**Annual vs monthly-paid-12-months-in-advance?**
80+
Annual has no monthly consumption limits (net of API instalment limits). Monthly prepaid for 12 months keeps the monthly call limits but costs less than the regular monthly plan.
81+
82+
**Can I check the status of my subscription(s)?**
83+
Yes, in My Subscriptions (status and usage report), and per API in its dedicated section.
84+
85+
**Can 'Subscription payment' and 'Payment per request' co-exist?**
86+
Yes — payment method is per API. Tip: keep some wallet credit so that when subscription requests run out the API keeps working with single requests.
87+
88+
**I have run out of requests in my subscription. What can I do?**
89+
Renew immediately, switch to another plan, or fall back to single requests paid from the wallet (top up if needed).

‎knowledge/oas/00-list.txt‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
https://console.openapi.com/oas/en/oauth.openapi.json
2+
https://console.openapi.com/oas/en/oauthv2.openapi.json
3+
https://console.openapi.com/oas/en/company.openapi.json
4+
https://console.openapi.com/oas/en/smsv2.openapi.json
5+
https://console.openapi.com/oas/en/esignature.openapi.json
6+
https://console.openapi.com/oas/en/risk.openapi.json
7+
https://console.openapi.com/oas/en/ai.openapi.json
8+
https://console.openapi.com/oas/en/trust.openapi.json
9+
https://console.openapi.com/oas/en/geocoding.openapi.json
10+
https://console.openapi.com/oas/en/invoice.openapi.json
11+
https://console.openapi.com/oas/en/automotive.openapi.json
12+
https://console.openapi.com/oas/en/docuengine.openapi.json
13+
https://console.openapi.com/oas/en/visurecamerali.openapi.json
14+
https://console.openapi.com/oas/en/realestate.openapi.json
15+
https://console.openapi.com/oas/en/cap.openapi.json
16+
https://console.openapi.com/oas/en/visengine.openapi.json
17+
https://console.openapi.com/oas/en/catasto.openapi.json
18+
https://console.openapi.com/oas/en/ufficiopostale.openapi.json
19+
https://console.openapi.com/oas/en/pecmassiva.openapi.json
20+
https://console.openapi.com/oas/en/pdf.openapi.json
21+
https://console.openapi.com/oas/en/marchetemporali.openapi.json
22+
https://console.openapi.com/oas/en/pec.openapi.json
23+
https://console.openapi.com/oas/en/bollettini.openapi.json
24+
https://console.openapi.com/oas/en/exchange.openapi.json
25+
https://console.openapi.com/oas/en/domains.openapi.json
26+
https://console.openapi.com/oas/en/gatewaysms.openapi.json
27+
https://console.openapi.com/oas/en/sdi.openapi.json
28+
https://console.openapi.com/oas/en/imprese.openapi.json
29+
https://console.openapi.com/oas/en/firmadigitale.openapi.json

‎knowledge/oas/ai.openapi.json‎

Lines changed: 1 addition & 0 deletions
Large diffs are not rendered by default.

‎knowledge/oas/automotive.openapi.json‎

Lines changed: 1 addition & 0 deletions
Large diffs are not rendered by default.

‎knowledge/oas/bollettini.openapi.json‎

Lines changed: 1 addition & 0 deletions
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)