canonical: https://jentic.com/apis/example.ilucca.net/lucca-organization # Example Ilucca Organization structure API Lucca Organization Structure exposes the company's organizational backbone - axes, axis sections, and departments - that the rest of the Lucca HR suite hangs employees off. Agents read department trees, list axis sections, and update structural metadata so reporting lines and cost-centre groupings stay in sync. It is the structural counterpart to Lucca Directory's user records. ## For AI agents Read and manage Lucca's department trees, axis sections, and organisational axes that group employees for HR reporting. ## Scope Does not handle individual user records, payroll, or expenses - use for axes, axis sections, and department structure only. ## Capabilities - List organisational axes used for grouping employees across the Lucca suite - Retrieve axis sections that subdivide an axis into reporting buckets - Look up a specific axis section by id for org-chart rendering - Fetch the full department tree for an organisational hierarchy view - Retrieve a single department by id including its parent and metadata - List all departments to feed downstream HRIS or analytics systems ## Use cases ### Org chart rendering An internal portal needs an up-to-date org chart. The integration agent calls GET /api/v3/departments/tree to retrieve the full hierarchical structure in a single response, then renders nodes with names, ids, and parent links - no recursive walking of individual department endpoints required. Example prompt: Call GET /api/v3/departments/tree, parse the hierarchy, and return a flat list of departments with their parent ids for org-chart rendering. ### Cost-centre and reporting axis sync Finance wants every Lucca axis section mirrored as a cost centre in the accounting system. The agent lists axes, then for each axis pulls its sections via /api/v3/axisSections, and upserts each section as a cost centre downstream so financial reports stay aligned with HR groupings. Example prompt: List all axes, pull the axis sections for each, and upsert them as cost centres in the accounting system using the section id as the external reference. ### New-hire department assignment When onboarding a new employee, an HR agent needs to confirm the target department exists before assigning the hire to it. The agent calls GET /api/v3/departments/{departmentId}, validates the response, and proceeds with the user creation only if the department is active. Example prompt: Retrieve department 17 via GET /api/v3/departments/17 to confirm it exists, then proceed with assigning a new hire to that department. ### AI agent org-aware reasoning via Jentic An AI assistant integrated through Jentic uses Lucca Organization to reason about who reports to whom. When asked 'who is in the Engineering department?' the assistant pulls the relevant department record and combines it with Directory user lookups, all without ever holding the raw API key. Example prompt: Use Jentic to search for 'list Lucca departments', load the operation, and return all departments whose name contains 'Engineering' for downstream user filtering. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /api/v3/axes | List all organisational axes | | GET | /api/v3/axisSections | List axis sections | | GET | /api/v3/axisSections/{axisSectionId} | Retrieve a specific axis section | | GET | /api/v3/departments | List all departments | | GET | /api/v3/departments/tree | Fetch the full department hierarchy | | GET | /api/v3/departments/{departmentId} | Retrieve a specific department | ## Key resources - **Axis-sections** — Subdivisions of an organisational axis used to group employees - **Departments** — Hierarchical department records with parent/child relationships ## Why Jentic - **Setup:** Wiring the Lucca Organization structure API by hand means learning its header API key auth on your ilucca.net tenant host and tracking the axes, axis-section, and department endpoints yourself. Through Jentic you install once, import Organization from the API Directory, store the API key once, and your agent calls it. - **Permission scoping:** Organization puts the department id in the URL path (/api/v3/departments/{departmentId}), so a rule can pin your agent to one department and its section reads. You choose the operations it may call, and since these are read GETs the agent fetches structure data and changes nothing unless you add write operations. - **Credential handling:** Your Lucca API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'fetch the department tree' or 'list org axes', and Jentic returns the matching Organization operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Lucca Directory** — User records that reference the departments managed here - **BambooHR** — Unified HRIS with built-in org structure and employee records - **Personio** — European HRIS with department and employee management combined - **Workday** — Enterprise HCM with deep org-structure modelling for large organisations ## FAQ ### What authentication does the Lucca Organization API use? Lucca Organization uses an API key in the Authorization header. Through Jentic, the key is encrypted in your Jentic One instance and replaced with a scoped token at call time, keeping the raw secret out of agent context. ### Can I get the full department hierarchy in one call? Yes. GET /api/v3/departments/tree returns the entire department hierarchy with parent and child relationships in a single response, removing the need for recursive lookups. ### What is the difference between axes, axis sections, and departments in Lucca? Axes are top-level grouping dimensions (e.g., cost centre, location). Axis sections are subdivisions within an axis. Departments are the canonical hierarchical org structure. The API exposes endpoints for all three at /api/v3/axes, /api/v3/axisSections, and /api/v3/departments. ### What are the rate limits for the Lucca Organization API? The OpenAPI spec does not publish explicit rate limits. Lucca applies tenant-level throttling at the platform layer, so agents should handle 429 responses with exponential backoff and respect Retry-After headers. ### How do I fetch the department tree via Jentic? Run pip install jentic, search for 'fetch lucca department tree', load the GET /api/v3/departments/tree operation, and execute. Jentic returns the hierarchical response so the agent can render or sync it without parsing the spec. ### Does Lucca Organization include user-to-department assignments? The Organization spec covers the structural side: axes, axis sections, and departments. Individual user assignments live on user records in the Lucca Directory API - call both APIs together to pair employees with their department metadata. ### Can I limit what my agent is allowed to do with the Lucca Organization API? Yes. Because you run Jentic One yourself, your own rules decide which Lucca Organization operations and credentials the agent may use, so you can allow only the reads you want, such as GET /api/v3/departments/tree, GET /api/v3/axes, or GET /api/v3/axisSections. Since the department id sits in the URL path (/api/v3/departments/{departmentId}), a rule can pin the agent to a single department and its section lookups. These are read-only GET operations, so the agent fetches structure data and changes nothing unless you explicitly add write operations.